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archive entries 



Command 

Author- Maintained Library 

Dave Moon 
545 Technology Square 
Room 501, Ext. 3-6013 
10/29/73 

Name : archive_entries , are 
archive__calls, arc 

The command archive_entries prints listings of the entry 
points of the segments within an archive, and archive_calls 
prints listings of the entry points called by the segments in 
an archive. 

Usage ; 

are pathname 1 . . . pathnamen 

This will produce a list of all the entry points in all the 
segments of archives pathname 1. archive to pathnamen. archive. 

arc pathname 1 . . . pathnamen 

This will produce a list of all the entry points called by 
all the segments in archives pathname 1. archive to pathnamen. archive. 

Notes : 

Upon encountering bad arguments , are and arc will comment 
and then continue with evaluation of the next argument. 

By design, arc suppresses printing of calls to pl1_operators . 
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Active Function / Command 
Author-Maintained Library 
Student Information Processing Board 
Room 39-200, Ext. 3-7788 

4/13/73 



Name: assoc 



This procedure implements an associative memory, and is use- 
ful primarily for implementing exec^com variables. 

Osage : 

[assoc name] 

1) ncuae is a variable name which has been set to some 

value by a prior call to assoc__^set. (Input) 

The returned value is a varying character string representing 
the value associated with the supplied name. If the name was not 
found in the memory, the null string is returned. 

Entry : assocjset 

This entry is used to associate values with names. 

Usage ; 

assoc__set namel valuel ... namen valuen 

1) namei is a character string name of up to 32 characters. 

2) valuei is a character string value of up to 168 characters. 

Entry ; assoc^clear 

This entry clears the associative memory 

Usage ; 

assoc_clear 

There are no arguments. 



Entry : assoc_list 

This entry lists the contents of the associative memory. 



assoc 
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Usage ; 

assoc_^list 

There are no argximents. 

Entry ; assoc^seg 

This entry is provided to allow assoc to reference an associa- 
tive memory in a permanent segment rather than the default 
per-process memory. 

Usage ; 



assoc^seg segname 

1) segname is the pathname of the segment to be used. If the 
segment is not found, it will be created. If seg- 
name is missing, or is the null string, assoc will 
revert to the per-process associative memory table. 
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Command 

Author-Maintained Library 
Robert F. Mabee 
5k5 Technology Square 
Room 518/ Extension 5871 

2/27/71 



Name ; bcpl 

BCPL Is a language designed for but not limited to system 
building and compiler writing. It is easy to read^ but is 
recommended primarily for experienced programmers. 

The bcpl command Invokes the BCPL compiler to translate a 
source segment into a Multics object segment. A listing segment 
may optionally be produced. The object and listing segments are 
placed in the current working directory. 



Usage: 

bcpl 

1) pathname 

2) Option! 



pathname optionl optlon2 



opt ionn 



is the pathname of the source segment. The 
compiler will append the suffix ".bcpl". 

are chosen from the following set: 

source produces a line numbered listing of the input 
text/ including text inserted bv get . 

xref produces a cross reference table in the 

1 1 sting segment. 

alist produces a complete assembly-like listing for 
the object program. 

list combines the effects of the source^ xref, and 

al 1st options . 

tree produces a listing of the syntax tree in the 

1 1 sting segment. 

check inhibits generating the object segment. 

time causes timing information to be printed on 

the console after each pass. 

crep is a debugging tool. It compiles input from 

the console and directs the listing output to 
the console. 
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pprep Is a debugging tool. It lists canonical 
symbols as they are encountered. 

Notes; 

The entry name portion of pathname is used as the name for 
the object segment. For the listing segment ".list" is appended 
to the entry name. The name of the source segment is obtained by 
appending ".bcpl" to pathname. 

The * get ' preprocesser convention is implemented as follows: 

The reserved word get must be followed by a string 
constant. All text remaining on the line after the 
string constant is ignored. The string identifies a 
segment of BCPL source which is to be logically 
inserted into the program. The name is formed by 
appending ".bcpl" to the string constant. The segment 
(or a link to it) must be in the current worlcing 
di rectory. 

A BCPL manual and Multics implementation guide will be 
available soon. 
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Command 

Author-Maintained Library 
Thomas Casey 
575 Technology Square 
CISL, Fifth Floor 
491-6300, Ext. 237 
1/8/74 



Name; blip 



The command blip types a short character string (a "blip") 
on the console every few seconds of CPU time used by the user's 
process. Both the time between blips and the type of blip may 
be specified by the user. A sequence of different blips that 
are to be cycled through also may be specified by the user. Blips 
will be typed out until the blipjoff command is given. 

Usage ; 

blip time -options amd/or blips- 

This command takes an unlimited niamber of arguments. The 
first argument is the time in CPU seconds between blips. Because 
this is a floating-point number, times of less than one second 
may be specified. This time will be adhered to exactly. If 50 
blips are given during the course of working, 50*time seconds 
of CPU time were used by the process. The command will even 
try to remain faithful if the time specified is less than the 
amount of time required to execute the blip program. If the 
time is about two seconds or more, it is estimated that the over- 
head for the blip program is about 0.1 second per blip. 

The rest of the arguments are either options or character 
strings to be used as blips after they have been modified as 
specified by the options. Because the arguments are processed 
from left to right, blip strings can be affected only by options 
to the left of the string. The options are: 

-red A red ribbon shift is added at the beginning 

of the blip string and a black ribbon shift 
is added at the end. 

-black (-bl) No ribbon shifts are added to the blip string. 

-nla (-nl) A new line character is added at the end of 

the blip string (newline after) . 

-nib A newline character is added to the beginning 

of the blip string (newline before). 



-nnl 



No newlines are added to the blip strings. 



I blip ) 
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If no options are specified, the options -red and -nnl 
are in effect. If no blip strings are specified, then the 10 
decimal digits from 0 through 9 will be the 10 blip strings 
to be cycled through. The first blip is typed out during the 
blip command, and it is the first blip string. The second 
blip is the second blip string. If n blip strings have been 
specified, then the n+lst blip will be the first blip string. 

Blips are always typed on the console, even when using 
filejoutput. 

Entry : blipjoff 

This command turns off the blips from the previous use of 
the blip command. If a blip is being given, another use of the 
blip commamd will turn off the previous blip automatically. 

Examples : 

blip 2 

Or 1133 1.302 4.108 93 
plT new_j)rogram 
lPL/1 

2345678r 1140 15.137 29.763 749 

new ^program 

901 

QUIT /*got into an infinite loop*/ 

r 1141 8.548 5.296 123 



© Copyright 1974, Massachusetts Institute of Technology 
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Command 

Authop-Malntalned Library 
Joseph W« Oehn III 
Room 39-200* Ext. 3-7788 

1/18/75 



N^w e » calc_costs» cc 



This command calculates the dollar cost of a given amount of 
CPU time* memory units* and connect time* 

calc^costs cpui meml « • • cpu£) memQ -connect X -shift K 

1) cpul specifies cpu time in seconds* The total cpu 

time is calculated by adding together all of the 
cpu times that are given. 



2) memi. 

3) -connect X 
i*y -shift K 



specifies memory usage in the units given in a 
ready message* The total memory usage is 
calculated by adding together all of the memory 
usage figures that are given. 

specifies the connect time in minutes. 

specifies the shift whose prices are to be used 
in the calculation of the dollar cost. If this 
control argument is not given* a table will be 
printed showing the cost for all shifts that are 
currently defined* 



calc.costs 1*007 6.728 -shift 2 
calc_costs 2*3 5*7 1*1 3.5 -connect 3 
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card_l nput 



Command 

Author-Maintained Library 
Overlap Project Staff 
NEltO-500, M.l.T. Ext. 3-2053 

2/5/75 



Name : card_i nput 



This routine may be used to read a deck of cards 
segment created in the user's working directory at the 
request is submitted. It supports the conventions about 
via linkS/ and provides the irol low! ng servi ces : 



into a 
time the 
readi ng 



1) The user need not be concerned about a "temporary name" 
and a "permanent name" the name appearing in the 

segment name field of the control card (1) placed at the 
beginning of the deck Is the name of the segment which 
will be created and into which the card images will be 
copied. 



2) The user need not be concerned with eliminating a link 
which may later cause problems^ because the program 
removes the link when the cards are copied. 

Use of this program greatly simplifies the task of reading 
cards on Multics, to the extent that it may be used with little 
instruction, even by a new user. Such instruction might be 
succinctly stated, "Put the name you wish the segment to have in 
the segment name field of the first (Control) card, submit the 
deck for reading, and then execute this program from the 
directory In which you want the segment to reside, using the same 
name that appears on the control card as the command argument." 

The program may also be used to copy an arbitrary segment 
via a link to it, effectively changing the name on the link to 
the name on the segment. 



(1) For details concerning the format of and Information required 
to use control cards, please see the M.l.T. Information 
Processing Center publication MS-1, "Bulk I/O on Multics." Note, 
however, that this publication describes a series of naming rules 
that this command makes unnecessary. 



card_i nput 
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card_input carcl_deck_name 

card_deck__name is the name that appears in the segment name 

field on the first (control) card of the deck. 

Not?: 

This command must be invoked from within the same directory 
as that appearing in the directory name field on the first 
(control ) card of the deck. 

Method: 

The experienced Multics programmer may desire to know the 
steps undertaken by the program during execution. An outline of 
the steps is: 

1) The name supplied in the command line argument is checked 
to ensure that it exists and is a link, and that the link 
refers to an existing segment. 

2) A uniquely named segment is created in the working 
directory; the segment referred to by the link is copied 
into the uniquely named segment. 

3) The link is unlinked, and the uniquely named segment is 
renamed to the name that was on the link. 

If any error occurs, the program displays a message and 
returns. 
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Conanand 

Author-Maintained Library 
Student Information Processing Board 
Room 39-200, Ext. 3-7788 

8/04/74 



Name ; clean-up 

The clean_up command enables the user to clean a directory or 
directory subtree of worthless entries: segments that have not 
been used or modified since some specified time; links that point 
to a non-existent target, and directories that contain no entries 
at all. 

Usage : 

clean_up -path- -options- -control^args- 

1) path is the pathname of the directory that is to be 

cleaned up or " -working jiirectory" ("-wd") . If 
neither is given then the current v/orking directory 
is assumed. 

2) options indicate which entries are to be deleted. They can 

be selected from the following list: 

-date__tim.e_inodif ied, -dtm 

specifies that segments found in the directory 
that have not been modified since a particular 
time are to be deleted. This argument can be 
followed by a string giving the desired time in 
format acceptable to convertjdate__to_binary_^. If 
a time is not given by the user, one month prior 
to the current time is assumed. 

-date_time_used , -dtu 

specifies that segments found in the directory 
that have not been used since a particular time are 
to be deleted. As above, the user can specify the 
time he desires, or let one month before be assumed. 

-link, -Ik specifies that links found in the directory that 

point to a non-existent target are to be unlinked. 

-directory , -dr 

specifies that any inferior directories found in 
the directory that have no entries them.selves are 
to be deleted. 

If no options are specified, segments not used in 
the last month will be deleted. 



cleanjup 
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3) control_args are selected from among the following 



-long, -Ig 



-brief, -bf 



-force 



-walk, -wk 



produces a listing of the directories searched and 
entries deleted. This listing is written on 
user__output and includes the date/time dumped for 
segments and directories and the target of a link. 
This is the default. 

suppresses the listing described above. ("-long" 
is the default) . 

specifies that entries are to be deleted even if 
their safety switch is set. If this argument 
does not appear, an error message will be printed 
when an attempt is made to delete such an entry. 

specifies that cleanjup is to walk through all 
inferior directories of the directory specified 
looking for entries to be deleted. Note that the 
contents of a directory are examined for deletion 
before a check is made to see if the directory is 
empty. As a result, if "-dr" has also been specified 
and if all the entries are deleted from an inferior 
directory, then that directory will also be deleted. 



-walk force, -wf 



specifies that inferior directories are to be walked 
as 2±>ove, and that cleanjap is to ensure that the 
user has "sma" access to each inferior directory. 



Examples : 

To delete all segments in the current working directory that 
have not been modified in the last month: 



c lean jap -da te_J: ime jmod if ied 

To remove all links that point to a non-existent target in 
the directory temp and all directories under it: 

clean-up temp -link -walk 

To delete all segments that have not been used since July 1, 
1974 and all directories that are empty: 

cleanjap -wd -dtu "July 1, 1974" -dr 

To purge the entire directory subtree under "old" of old 
segments, null links, and empty directories (including those made 
empty by cleanjap) : 

clean-up old -dtu -dtm -Ik -dr -wf 
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Command 

Author-Maintained Library 
J.B. O'Connor 
Room 39-473, Ext. 6321 
11/12/70 



Name ; convert_360_pl1 , c360p 

This command converts an IBM 360 PL/I program read in by the 
Multics card reader to a form acceptable to the Multics PL/I 
compiler. Specifically it: 

1. maps all upper case letters in the file to lower case, 

2. changes all apostrophes (*) to quotes (") , 

3. deletes any characters appearing in card columns 73 through 
80 (sequence numbers) , and 

4. deletes trailing blanks on a line. 
Usage : 

convert_360__pl1 pathname 1 pathname 2 

Pathnamel is the name of the segment to be converted and 
pathname2 is the name of a new segment to be created to contain 
the converted program. If pathname2 is omitted, pathnamel will 
be rewritten. 



Notes : 



The translation does not take into account the 48-character 
set used in IBM 360 PL/I. For example, if the operator "LT" is 
used in the 360 program, the user must change this to the character 
"<" with a Multics editor. 

If character constants start on one card and end on another 
card in the 360 program, the effect of trimming off trailing 
blanks may change the value of the constant. 

Example : 

c360pll ibm.pll multics. pl1 



This command can be applied to segments that it had previously 
produced without effect. It cannot be applied to segments entered 
on the console, however, unless tabs have not been used and care 
has been taken to follow IBM 360 card conventions (because characters 
after the 72nd column on a line will be deleted) . 
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Command 

Author-Maintained Library 
Joseph W. Dehn III 
Room 39-200, Ext. 3-7788 

7/29/74 



Names ; convert__line_feeds , cvlf 



This command converts an ASCII segment which contains carriage- 
return and line-feed codes as used by other systems into a segment 
which uses the Multics new-line character. A combination of line- 
feed and carriage- re turn is replaced with a new- line character, 
a carriage-return by itself is left as is, and an isolated line- 
feed may be treated in one of three ways: deletion, replacement, 
or "simulation" by new-line and spaces. 



Usage ; 

convert_line_feeds pathl path2 -cntlargs- 

pathl is the pathname of the segment to be converted 

path2 is the name of the segment to be produced. If this 
argument is omitted, the conversion will be done in 
place (the new segment will replace the original) . 

Control arguments may be used to specify the handling of 
isolated line-feeds: 



-delete isolated line-feeds are to be removed 

-dl 

-replace xxx isolated line- feeds are to be replaced by 

the string xxx, which may be up to 32 
characters in length 

-space isolated line-feeds are to be replaced by 

a new- line and spaces to effect the carriage 
motion of a line- feed 

-teJa N specifies the width of a tabulation character 

when using the -space option. If this option 
is not given, tabs are assumed to be ten 
columns wide. 



Note: 



The ASCII carriage-return code is octal 015. The octal 
code for line- feed is 012. Multics uses the code 012 for new- 
line. A carriage-return/line-feed combination is treated by 
removing the code 015 from the text. 
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Command 

Author-Maintained Library 
Thomas Casey 
575 Technology Square 
CISL, Fifth Floor 
491-6300, Ext. 237 
1/8/74 



Name; convert multics fortran, cmf 



This ccmnand converts Multics FORTRAN programs into a form 
acceptable by IBM 360 FORTRAN. The command: 

1) changes lower-case characters to upper-case, 

2) changes quotes (") to apostrophes [*) , 

3) changes the continuation card convention from a to an "X" 
in column 6 of the next card , 

4) changes horizontal tabs to spaces, 

5) puts the first four characters of the output pathname into 
columns 73-76, 

6) sequences lines in columns 77-80, 

7) does not handle implied continuations, 

8) will continue lines greater than 72 characters in length onto 
the next card(s) , and 

9) always will put the segment following a continuation character 
on the next card. 

Usage ; 

cmf pathname 1 pathname 2 

Where pathnamel is the name of the segment to be converted 
and pathname2 is the name of the segment to contain the converted 
program. If pathname2 is omitted, the output will be under 
pathnamel" .360" . 

Example ; 

cmf multics . fortran 360. fortran 
OR 

cmf multics . fortran 

Pathname2 defaults to multics . fortran. 360 in the latter case. 

This command cannot be applied to segments which it had pre- 
viously produced. Non- FORTRAN lines in the program could con- 
ceivably cause incorrect operation. 
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Command 

Author-Maintained Library 
Joseph W. Dehn III 
Room 39-200, Ext. 3-7788 

8/7/73 



Name; convert radix, cvr 



This command will convert the character string representation 
of an integer in one radix into its representation in another radix 
and print it on the console » The input and output radices may be 
from 2 to 64, and the characters to be used as numerals may be spec- 
ified. 

Usage ; convert^radix input input^radix output__radix nximerals 

1) input is the number to be converted. 

2) input_radix is the radix to convert from. 

3) output_radix is the radix to convert to. 



4) numerals 



is a character string of up to 64 numerals. 



The "output_radix" and "numerals" arguments may be omitted. 
The former defaults to ten, and the latter defaults to, in order: 
the arable numerals, the capital letters, and the lower case letters. 
Note that if the numerals are to be specified, the output radix must 
be specified. 

If several numbers are to be converted in the same manner (same 
input and output radices and numerals), specifying as the first 
argument will put the program into a loop reading input from the 
keyboard, one number per line. This mode may be terminated by en- 
tering a blank line. 
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Command 

Author-Maintained Library 
Student Information Processing Board 
Room 39-200, Ext. 3-7788 

4/7/73 



Name; decimal to octal, dto 



The decimal^to octal command will convert a decimal argument 
to octal and print it on the console. 

Usage ; 

decimal_tojoctal decimal^number 
1) decimal^number is a decimal number to be converted to octal. 

Entry : octal^to jdecimal , otd 

This entry will convert an octal argument to decimal and 
print it on the console. 

Usage ; 

octal__tojdecimal octal_^number 
1) octal number is an octal number to be converted to decimal 
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Command 

Author-Maintained Library 
John C. Klensin 
575 Technology Square 
Fifth Floor, Ext. 3-6217 

2/20/74 



Name ; f ile_output_unique, fou 

This command facilitates dprinting the results of other 
commands • 

Usage ; 

f ile_output_unique [dp -options] 
command 1 

■• •■ • 

command n 

q 

where dp -options are zero or more of the options normally passed 

to the dprint command. These options include "-ds," "-he," and "-cp." 

The differences between the sequence 

fou 

command- line 1 
command- line 2 

• • • 

• • • 

command- line n 

q 

and the sequence 

file__output namel; command-line 1; console joutput 
file_output name2; command-line 2; console_output 
... 
... 

file_output namen; command-line n? console joutput 
dp -del namel name2 . . . namen 

are as follows; 

1. Each file produced by f ile__output_unique begins with a header 
consisting of the command line responsible and a time and date 
message. 

2. Each file produced by f ile__output_unique ends with a distinctive 
trailer line consisting of "END*END* . . . *END. " 



I f i le_jDutput__unique 
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Notes : 

1. file_output_unique interprets command lines with the user's 
command interpreter, whatever that may be. 

2. This version of f ile__output_unique does not require that the 
I/O daemon have any special privileges in the working directory. 

3. This routine uses f illin_dprint_str_ to evaluate "dprint" options. 
See the current description of that subroutine for an exact list 
of the options accepted 



Example ; 



fou 

pwd; Is -dtm 

pli big_motherj30\ind_jarchive 

q 



(c)Copyright 1974, Massachusetts Institute of Technology 
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Command 

Author-Maintained Library 
John C. Klensin 
575 Technology Square 
Fifth Floor, Ext. 3-6217 

7/9/74 



Name : get_current_charges , gcc 



This command is used to provide a project administrator with 
a variety of information in compact form about a particular user (or 
list of users) on a particular project. It can display amounts spent 
per shift during the current month, amounts spent absentee, and on io, 
and the number of pages in the user's directory. It can display the 
limits on the above, if any. In addition, it can display the user's 
attributes and the date and device on which he last logged in. 

Usage ; 

getjcurrentjcharges project-name user-name user-name ... options 
Where: 



project-name 



user-name 



options 



is the name of the project for which infor- 
mation is to be obtained. 

is the name of a user on that project for 
whom information is to be obtained. Up to 
20 user nsunes may be specified. 

are control arguments for the program. These 
may occur in any order, and may be intermixed 
with user names. Any options that occur apply 
to the entire command invocation. These options 
are : 



-total, -tt 

-limit 
-attributes 
-last_login, -11 

-absolute, -abs 



Display only the dollar 
total (and limit, if that 
option is used) . 

Display the limits, in 
addition to the charges. 

Display the user's current 
attributes . 

Display the time, date and 
console id of the user's 
last login. 

Display information about 
"absolute" spending and, if 
"-limit" is specified, limit 
and cutoff information. 



get_current_charges 
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Output ; 

If no options are specified, a single line will be displayed 
containing the user name, the total charge, the four shift charges, 
the io daemon and eQ:>sentee charges, and the page usage on the user's 
directory. If -total is specified, only the total charge will appear. 

The other options cause additional per-user lines to be displayed. 
These are as follows: 

For "-limit", a line showing the total limit, the four shift 
limits, and the user's page quota. If "-total" was specified, then 
only the total limit is printed. 

For "-attributes" a line is displayed showing the attributes 
as text strings. 

For "-last_login" , a line is printed containing the time, date, 
and console id, of the user's last login. 

Notes ; 

1) If errors occur for a given user, messages will be printed at 
the end of the information for that user. If the person using 
this program does not have access to get quota information, 
those fields will be set to zero and a message printed after 
other information. 

2) This command requires read access to the project definition table 
of the project for which information needs to be obtained. As 

a consequence, this command is of no use to any Multics user who 
is not a project administrator. 



Copyright 1974, Massachusetts Institute of Technology 
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getjobject_info 



Command/Active Function 
Author-Maintained Library 
Student Information Processing Board 
Room 39-200, Ext. 3-7788 

9/6/74 

Names ; get__object_info, goi 

get__component_inf o , gci 

These commands/active functions give information about the 
compilation of an object segment. 

Entry ; get_object_info, goi 

Usage : 

(as a command) getjobject_info path key 

(as an active function) Cget_object_info path key] 

1) path is the path of the object segment. 

2) key specifies the information to be printed/returned, 

and may be one of the following: 

author the user id of the user who produced the object 

at segment . 

date_^time_compi led 

dtc the date and time of the compilation. 

compiler the name of the translator that produced the 
object segment. 

version the version of the translator that produced 

the object segment. 

comment a translator inserted comment. The PL/I 

options compiler uses this field to indicate the 

options that were specified at compile time. 

Entry : get__component_inf o , gci 

This command/active function gives information about the 
compilation of a component of a bound object segment. 



getjobject_info 
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Usage ; 

(as a command) get_component__inf o path component_name key 

(as an active function) Cget_jcomponent_info path component_jiame key] 



1) path 

2) key 

3) component__neuiie 
Notes : 



same as above, 
same as eibove. 

is the name of the component of the object segment 
for which the information is to be returned. 



1) If the "component" argument to getjcomponent__inf o is omitted, 
it will be assumed to be the same as the entryname portion of 
the pathname. 

2) If "get_object_info" is used on a bound segment, it will return 
information about the binding. 

Examples ; 

getjobject__info xyz author 

get_component__info bound_xyz_ xyz dtc 

getjcomponent_info xyz version 
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lock console 



Command 

Author-Maintained Library 
B. E. Hampson 
Room 38-644, DL 9204 
03/11/74 



Names: lock console, Ike 



This command can be used to protect your process from unau- 
thorized use in the event you have to leave your terminal for 
any length of time. Lock^console has two modes of operation: 
one in which your process is simply put to sleep awaiting your 
return, and one in which lock__console will execute a command 
line under its protection. 



When in command- line- execute mode, lock_console will (by 
default) establish an on unit for the condition "any_other". 
The effect of this will be to "catch" any condition signalled 
by any procedure invoked by the command line. Lock_console 
captures the signal and prints a message to the effect that 
the signal occurred; but, unlike the system default on unit, 
the process is not returned to command level. Rather, lock_console 
calls itself recursively with a basic lock time and grace (see 
below) of 24 hours. If the user does not reclaim the terminal 
in 48 hours, he is either logged out, or lock_console returns to 
its caller. If the terminal is reclaimed, the signalling of the 
condition will continue just as if lock_console had not inter- 
cepted it. Note that, among other things, this feature prevents 
someone else answering a question for you (provided the question 
is asked in such a way as to cause a condition to be signalled, 
e.g. , command jquery^) . 

There is one exception to the above "signal-catching" scheme: 
if a quit is done while executing the command line, the user's 
password is requested. If correct, the quit is passed on and 
the process gets to command level. If incorrect, the quit is 
simply returned from. 

Protection is achieved by means of an 8-character password. 
Lock^console will request this password when invoked (see the 
listed exceptions below) either under overprint or with printer 
disabled. To reclaim a terminal, the procedure is to strike 
the QUIT key, and to enter the same password when it is requested. 



r 

\ lock console 
t 
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Usage ; 



lock console -controll- 



-controln- 



The control! are optional control arguments , and may be chosen in 
any order from the following list: 



-time TTT 

-tm TTT Sets the basic lock time to TTT minutes. 

This value is the time after which lock_console 
will take further action (in the absence of a 
grace period) , if the terminal has not yet 
been reclaimed. The default basic lock time 
is 10 minutes. 



-no_^logout 

-nol Specifies that, at the expiration of the 

basic lock time (and the grace period, if any) , 
lock_console is to return to its caller in- 
stead of logging the user out. The default 
is to log the user out. 



-prev_pw 

-ppw Specifies that the password from the previous 

invocation is to be used (a new password will 
not be requested if this argument is used) . 
This argument will be ignored (with consent) 
if it is used in the initial invocation in a 
process. 

-defer^messages 

-dm Specifies that the command "def er jnessages" is 

to be executed (before executing the command 
line, if any). The command "immediate_mes sages 
-print" will also be executed, just before 
lock console returns to its caller. 



-set^w PPP 

-spw PPP Sets the password for this invocation to PPP. 

This argument overrides -ppw if both are used. 
PPP is limited to eight characters. 



-call CCC 

-cl CCC Requests that the command line CCC be passed to 

the user's command processor for execution under 
the protection of lock__console. The real time 
required to execute the command is counted against 
the basic lock time, but the grace period does 
not begin until after the command line has fin- 
ished executing. 
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•grace GGG 
-gr GGG 



Sets the grace period to GGG minutes . Lock_console 
will neither return nor log out, after the basic 
lock time has been exceeded (or after the command 
line has finished executing, whichever is longer) , 
until this grace period expires. The default 
grace is 0 minutes (no grace) . 



-no catch signals 



-ncs 



-brief 
-bf 

■ no__p r i n t_o f f 
-npf 



Specifies that during the executing of the command 
line, lock__console is not to establish an on unit 
for the condition any other. The default is to 
provide such an on unrt. A command line running 
in "no catch" mode cannot be quit out of by some- 
one who does not know the password; however, if 
some error or other condition is signalled and 
the user has no on unit for it, the process will 
get to command level via the system default on 
unit, and then be vulnerable to unauthorized use. 



Causes lock console to be less verbose 



Specifies that the user's terminal does not have 
the printer off feature, and that therefore the 
user desires his passwords be requested under 
overprint. 



Example ; 

lock_console -tm 25 -no_logout -grace 2 -cl "Is -p <" -bf 



cj Copyright 1974, Massachusetts Institute of Technology 
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lower case 



Command 

Author-Maintained Library 
J. R. Steinberg 
Room 39-427, Ext. 3-7184 

1/8/74 

Name ; lower_case 

This command, given the pathname of an ASCII file, maps all 
upper-case letters in the file to lower case. It is intended for 
use on card-punched decks which have been input to Multics and which 
contain source code for a compiler which expects lower-case keywords 
(e.g., PL/I, FORTRAN). 

Usage 

lower_case pathname 

Where pathname is the pathname of an ASCII file which is to be 
mapped to lower-case. 
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number jqueued 



Active Function/Command 
Author-Maintained Library- 
Student Information Processing Board 
Room 39-200, Ext. 3-7788 

5/10/74 



Name ; number jqueued , nq 



This procedure returns the number of requests in an I/O 
daemon queue . 

Usage ; 

(as active function) : [number jqueued qnum dvc] 

(as command) ; number jqueued qnum dvc 

1) qnum a positive integer which specifies the queue number 

2) dvc the name of the device class (optional) 
Example ; 

As an active function, the procedure may be used by an 
exec com or absin control program to decide in which queue to 
submit a request: 

&if [greater [nq 3] 153 &then dp -q 2 sample. list 

&else dp -q 3 sample. list 



MULTICS PROGRAMMERS' MMJUAL 



octal to float 



Command 

Author-Maintained Library- 
Student Information Processing Board 
Room 39-200, Ext. 3-7788 

4/7/73 



Name ; octal_to_f loat, otf 

The octal_^to_f loat command will print the floating point value 
of an octal argument on the console. 

Us age ; 

octal_to_^f loat octal^niamber 
1) octal number is an octal number to be converted to float. 



Entry ; f loat^tojoctal, fto 

This entry will print the octal representation of a floating 
binary argument on the console. 

Usage ; 

f loat_to_octal float_number 
1) float number is a float number to be converted to octal. 
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print basic file 



Command 

Author-Maintained Library 
Joseph W. Dehn III 
Room 39-200, Ext. 3-7788 

7/29/74 



Name: orint basic file 



The printj3asic_f ile command may be used to print the contents 
of a file as interpreted by the BASIC language. The file may be 
terminal- format, random-string, or random-numeric. 



Usage ; 

print_basic__f ile file^spec 

where file__spec is a string specifying the file to be printed. 

If the string contains blanks, it must be enclosed in quotes. The 

type of the file will be printed, follov/ed by the contents. 
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print_login_dir 



Command 

Author-Maintained Library 
John C. Klensin 
575 Technology Square 
Fifth floor. Ext. 6217 
1/18/71 



Name ; print_login_dir , pld 



The print__login_dir command causes the name of the original 
login directory to be printed on the console. 



Usage ; print__login dir 
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print string 



Command 

Author-Maintained Library 
Room 39-2009, Ext. 3-7788 

5/10/74 

Name ; print_^string, ps 

print_string__nnl, psnnl 
print_string__ht, psht 
print__string__tb, pstb 

This procedure prints on the console the line formed by 
concatenating its arguments, with one blank between each argument. 
The entries differ only in the character appended at the end of 
the line, which is as follows: 



Entry 

print__string 
print_string_nnl 
print_string_ht 
pr in t_s tr ing^^tb 



Abbreviation 
ps 

psnnl 

psht 

pstb 



Trailing Character 

newline 
(none) 

horizontal tab 
space 



Usage ; 

print_string argl . . . argn 
Example ; 



print_string Cpath &1] as of Mate] 
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punch_paper_tape 



Command 

Author-Maintained Library 
Joseph W. Dehn III 
Room 39-200, Ext. 3-7788 

5/15/73 



Name : punch_paper__tape , ppt 



This command punches an ascii segment on the paper tape punch 
of a model 33, 35, 37, or 38 teletype. The segment may be punched 
as is, or carriage returns may be inserted at the end of each 
line. The file is preceeded by a punch-on (device control 2) 
character and a leader of nulls, and followed by a trailer and a 
punch-off (device control 4) . 

Usage ; punch jpaper__tape < optl> ... <optn> <pathl> ... <pathn> 

Options take effect as found in the argument list, and should 
normally preceed all path arguments. 

-insert^cr enables the insertion of carriage returns and 
-icr null padding at the end of each line. 

-override causes the fact that you are not on a teletype 
to be ignored. 



Notes ; 

When in -icr mode, each \012 is replaced by \015, \012, \000. 
In addition, a punch-on character is added after each punch-off, 
to allow the punching to continue. When not in -icr mode, no 
processing is done at all. In either mode, all other characters 
are sent as is, including \004 and \005, whose effects on the 
particular terminal should be considered when trying to punch 
out strange segments. Note that this command cannot be used to 
punch non-ascii files since the high-order bit of each byte is 
lost. 

Examples ; 

ppt -icr foo.fortran test. basic 

punch_j)aper_tape -override saonple^^f ile 



MULTICS PROGRAI^IMERS' MANUAL 



push v/dir 



Command 

Author-Maintained Library 
Student Information Processing Board 
Room 39-200, Ext. 3-7788 

9/6/74 



Names : pushjwdir, pop__wdir 

These commands may be used to change the working directory 
while pushing the previous working directory onto a "stack". The 
previous working directory may then be restored. 

Entry : push__wdir 

This entry changes the working directory and pushes the previous 
working directory. 



Entry : pop__wdir 

This entry restores the working directory to the value pushed 
by the push_wdir command. 



Usage ; 



push_wdir path 



1) path 



is the pathname of the new working directory 



Usage : 



pop wdir -control arg- 



The control argument "-all" specifies that the working 
directory should be restored to what it was before the first 
push wdir command, i.e., the "stack" is popped all the way. 
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read jflar tmbu th_tape 



Coimnand 

Author-Maintained Library 
Joseph W. D^hn III 
Room 39-200, Ext. 3-7788 

7/27/74 



Names ; read_dartmouth_tape , rdt 



The readjdartmouth_tape command may be used to read all or 
some of the files on a Dartmouth library tape into Multics segments 
The tape is assumed to be a 9- track image of a 7-track "format 1" 
ASCII tape, with the first file being a directory. 



Usage ; 



readjdartmouth__tape -control_args- -f ile_^names- 



1) -tape xxxxx 

2) -hold 

3) -all 

4) -trace 

5) -list 

6) -noconversion 

7 ) -name 

Notes : 



specifies the volume_id of the tape to be read. 
If this argument is not specified, it is 
assumed that the stream "dart_tape" is already 
attached to the appropriate device. 

specifies that the tape is not to be detached 
after the files have been read. 

specifies that all files on the tape are to 
be read. If this option is given, no file 
names may be specified. 

specifies that as each file is encountered on 
the tape, its number and name are to be printed. 

specifies that a file is to be created with the 
name "tapeid.dliblist" listing the name and 
type of all files on the tape. 

specifies that no conversion is to be done 

for "random-string" and "random-numeric" files. 

specifies that the following argument is to 
be treated as a file name, even if its first 
character is 



1) Files on the tape are in one of three formats. "TERTIINAL- 
FORMAT" files are read with no conversion. "RANDOM" files 
are converted into a form suitable for use with the Multics 
BASIC language, unless the -noconversion option is specified. 



2) Darmouth file names are usually composed of upper-case letters. 
When specifying file names, be sure to spell them exactly as 
listed in the tape directory. 



read_dartmouth_tape 
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Examples ; 

To read all files and create a directory listing: 

rdt -tape 12345 -list -all 
To read two files and hold the tape: 



rdt -tape 54321 -hold RATINV TRUTHTAB 
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reformat line 



Command 

Author-Maintained Library 
Elaine Franklin 
575 Technology Square 
Cambridge Project 
Fifth Floor, Ext. 2054 

9/9/71 



Name; reformat line, rfl 



The reformat__line command may be used to scan a segment line- 
by-line, forcing each line to fit into a specified number of 
columns • 



Usage ; 

reformat_line pathnamel [pathname2] [-start ccl] [-end cc2] [-wrap cc3] 
or 

rfl pathnamel [pathname2] [-start ccl] [-end cc2] [-wrap cc3] 
Where : 

is the pathname of the input segment. 



pathnamel 
pathname 2 

ccl 



cc2 



cc3 



is the pathname of the output segment. If 
pathname2 is not supplied, then the segment 
pathnamel will be replaced upon completion of the 
command . 

is the column in which a line normally starts. 
If ccl is not supplied, then it is assumed to be 
1. ccl may not be less than 1 nor greater than 
132 or cc2. If supplied, ccl must be preceded 
by the string "-start" . 

is the last column incorporated in a line before 
it wraps. If cc2 is not supplied, then it is 
assumed to be 80 . cc2 may not be greater than 
132 nor less than ccl. If supplied, cc2 must 
be preceded by the string "-end". 

is the column at which a wrapped line is to start. 
If cc3 is not supplied, then it is assumed to 
be 1. cc3 may not be less than 1 nor greater than 
132 or cc2. If supplied, cc3 must be preceded 
by the string "-wrap". 



reformat line 



Page 2 
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The program re forma t__line is designed to scan a segment line~ 
by-'line and reformat it as follows. Any horizontal tabs which are 
encountered during processing will be converted to the appropriate 
number of blanks before further processing of the line is done. 
Lines will be reformated so that they will begin at column ccl and 
continue up to and including coliamn cc2. If a line is longer 
than cc2-ccl+l characters, it will be broken up or reformated to 
continue onto the next line, beginning in the column specified 
for cc3 and continuing through coliimn cc2 of that line. If ccl 
or cc3 is greater than 1, blanks will be inserted in columns 1 
through ccl-1 or cc3-l, respectively. 



Examples : 

re forma t__line alpha 

would take the segment alpha in the current working directory and 
reformat it using the default values for ccl, cc2 and cc3 (1, 80 
and 1, respectively) . The old segment alpha would be replaced by 
the new segment alpha in the current working directory. 



ref ormat__line -end 132 beta -wrap 60 gamma 

would take the segment beta in the current working directory and 
reformat it: using the default value of 1 for ccl and the values 
132 and 60 for cc2 and cc3, respectively. An output segment neimed 
gamma would be formed in the current working directory. 



Warning : 

This command considers anything of the form "character back- 
space character" (e.g.. A) to be three separate character positions. 
If this action inconveniences anyone, please contact Elaine Franklin, 
Ext. 2054. 
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repeat 



Command 

Author-Maintained Library 
Student Information Processing Board 
Room 39-200, Ext. 3-7788 

4/7/73 



Name ; repeat 

The repeat command makes it possible to have a command line 
repeated any number of times. 



Usage ; 

repeat [-times n] command^line 

1) n is the number of times to repeat the command. 

If the -times option is omitted, the command 
will be repeated indefinitely. 



2) command line 



is the command line to be repeated. It need 
not be enclosed in quotes. 
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t Zl , 

Command 

Author-Maintained Library 
Paul Green 
Honeywell - DSO 
575 Technology Square 
491-7300 
1/9/74 

Name ; return^to, rt 

This command will cause a return to a procedure which called 
out from a specified stack frame, thus simulating a normal return 
from that call. 

The return_to command is simply an interface to the system 
subroutine "unwinder_" ; refer to the MPM Subsystem Writer's Guide 
for complete information. 

Usage ; 

return^to frame 

The command argument "frame" is the octal offset of the stack frame 
(in the current ring) to be returned to. This offset may easily be 
determined by using the ".t" request to "debug," or the "trace^stack" 
command . 

Example : 

return_to 5540 

will return to the procedure owning the stack frame at octal offset 
5540 in the current ring's stack. 
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ring 



Active Function/Command 
Author-Maintained Library 
Student Information Processing Board 
Room 39-200, Ext. 3-7788 

5/10/74 



Name : ring 

This procedure returns the current ring of execution. 
Usage ; 

(as active function) : [ring] 
(as command) : ring 
Example: 



&if [equal [ring] 5] &then subsysjwho &1 &2 &3 &4 

&else who &1 &2 &3 &4 
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subtree status 



Command 

Author-Maintained Library 
Gary M. Palter 
Room 39-200, Ext. 3-7788 

11/29/73 



Names ; subtree_status, stst 
directory_status , dst 
global_status> gstat 

This command is related to the status command. It will produce a 
listing of a subtree of the hierarchy (or just a single directory) 
with complete information about all (or some) of the entries in 
each directory. It also will list the quotas and Initial Access 
Control Lists of each directory. 

Options exist to specify the type of sort to be performed on entries 
in a directory, to specify which classes of entries are to be listed 
(similar to the list command) , and how multi-segment files are to be 
treated. 

Output is in a format suited almost solely for dprinting. The 
field width is 136 characters, and there are form-feeds at the start 
of each directory's listing. 



Usage : subtree^status , stst 

subtree__status -directory- optionl- 



-optionn- 



1) directory 



2) option! 



-brief, -bf 



-check, -ck 



is the relative pathname of the directory which 
is the top node of the hierarchy to be listed. 
If the directory is omitted, the working direc- 
tory will be used. 

is chosen from the following list of options 
(see also Notes below) : 

will cause any messages which might be expected 
not to be reported through com__err__. See the 
Notes below. 

will cause subtree_status to walk any multi- 
segment files that do not conform to the rules 
for multi- segment files (in the write-up of 
check msf ) like any other directory. 
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-name, -nm specifies that the entries in a directory are to 

to be sorted by primary entry name in the listing. 

-date__time_used, -dtu 

specifies that the entries are to be sorted by 
date time used in the listing. 

-date_time jnodified, -dtm 

specifies that the entries are to be sorted by 
date time modified. 

-segment, -sm specifies that segments are to be included in the 

listing (see Notes) . 

-directory, -dr specifies that directories are to be included in 

the list. 

-multisegment_file, -msf 

specifies that multi-segment files are to be 
included . 

-link, -Ik specifies that links cire to be included. 

Notes : 

1) The messages suppressed by the -brief option are those concerning 
insufficient access to a directory, or a directory containing 
none of the entries selected for listing. 

2) If any one of the arguments for selection of entry classes for 
the listing is present, then information only about those classes 
for which an option appears will be given. 

3) Only one of the sorting options may be given per command. 

4) The defaults for the options are: 
-brief off 

-check off 

sorting none 

selection all entry classes 

5) An example of the output produced by this command appears below. 
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6) The "Records" field of a segment or directory entry is the num- 
ber of non-zero pages for that branch. The "Blocks" field is 
the length of the segments in blocks of 1024, (These two numbers 
will be different only if there are pages containing all zeroes.) 

7) The "Bit Count" field of a multi-segment file entry is the number 
of segments inferior to the multi-segment file. The "Records" 
field is the nimiber of pages used by the directory portion of 

the multi-segment file. The "Total" field is the number of records 
in the multi-segment file (the scune value that is returned by the 
list command) . 

8) If the target of a link does not exist, an asterisk will be 
placed in the "Null" field of the link's entry. 

Usage ; di rectory _s tatus , dst 

directory's tatus -directory- -optionl- . . . -optionn- 

The arguments are identical to those for subtree_status . This 
entry differs from subtree__status in that it does not walk the sub- 
tree of the specified directory, but produces a listing of only that 
directory. As a consequence, the -check option is meaningless for 
this command. 



Usage ; global^status , gstat 

global_status -directory- -optionl- . . . -optionn- 

The arguments are identical to those for directory's tatus . This 
entry differs from directory_status in that the default sorting op- 
tion is date time used (instead of no sort) . This entry is provided 
as a replacement for an older version of the gstat command. 
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Pal ter* Janus.a 



r H 
r M 
r 



Palter.Janus** 
*.SysOaefflon.* 



Used 
Hodlf led 



Dumped 
Entry Modified 



Bit Count Retords Safety 
Hax Length BlocKs Copy 



Mode Access 10 



11/28/73 0313 
11/28/73 0313. 

rew 
re 



11/28/73 0326 
11/28/73 0315 

Pal ter.».» 
♦.SIPBAOMIN.* 



0 

65536 



off 
off 



No Directories* 



Primary Name 

Secohdary Name(s) 
a.mul tlsegment.fi le 



Ring 
Brackets 



(7,7) 



Multi-Segment Fllesi 1 



Author 

Bit Count Author 



used 
Modified 



Dumped 
Entry Modified 



Bit Count Records Safety 
Max Length Total Copy 



Mode 



Access 10 



Mode Access tO 



Pal ter. Janus.a 
Pal ter. Janus.a 



11/28/73 0328 
11/28/73 0310 



11/28/73 0325 
11/28/73 0310 



5 

65536 



1 
69 



off 
off 



a_msf . 



sma Palter.Janus.* 



sma *.Sys0aemon.* 



Llnksi 1 

Primary Name Author Modified Dumped 

Null Pathname 

Secondary Name(s) 



empty 



Pal ter. Janus.a 11/28/73 0311 

• >user_dlr_dir>Janus>Pal ter>em0ty 



01/01/01 1900 
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Command 

Author-Maintained Library 
Peter B. Bishop 
5kS Technology Square 
Room 536, Ext. 6213 
03/26/72 



CHAPTER 1 
TECO 



TECO (Xext £ditor and Corrector) is a character oriented 
text editor modelled after the TECO in general use on the Digital 
Equipment Corp. PDP-10, which was originally written at M.I.T.*s 
Artificial Intelligence project. TECO allows many simple editing 
requests, macro definitions, iterations, and conditional 
statements. These permit the user to do simple "manual" editing 
of ASCII files or to write complex macros which do "automatic 
editing. Although this implementation is modeled after the TECO 
in general use, many new commands and features have been added 
that make the macro facility really powerful and easy to use. 
Some of the additions include adding if ... then ... else ... 
statements, allowing the contents of Q-registers to be used as 
quoted strings, allowing numeric and string arguments to be 
passed to macros, and allowing macros that reside in files to be 
called directly from TECO. 



1.1 GENERAL DESCRIPTION 

TECO is basically a character oriented editor, whereas 
editors like edm and qedx are line oriented editors. In edm and 
qedx it is only possible to position the pointer to the beginning 
of the line. The pointer is then considered to point at the whole 
line. These editors then supply commands (the substitute or 
change command) to edit the current line. In TECO such a 
complicated command is unnecessary because the pointer can point 
between anv two characters in the buffer. The fundamental 
character oriented commands are insert, delete, search, and 
moving the pointer. V/ith these commands it is very easy to do 
what would be complicated operations in a line oriented editor. 
The concept of a line as an important entity is not unknown in 
TECO, however. There are many commands that can be line oriented. 
These are the L, T, K, X, and S commands. 

TECO reads command lines from the user's console (actually it 
reads from the stream "user_input ") line by line until a line 
ending with "$" is typed. Execution of the complete command 
string is started when this last line is read. TECO will type "E" 
when it is waiting for a new command string. 



teco 
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1.2 ENTERING TECO 

TECO may be called from the Multics command level by the 
Mult ICS command: 

teco -pathname- or TECO -pathname- 

If pathname is specified, TECO automatically reads in the file 
by effectively executing the string "E I /pathname/ J" upon entry. 
If no pathname is specified, the buffer will initially be empty. 
To create a new file, one should enter TECO (without specifying a 
pathname) and then use the "I" request to insert text, 

(See section 3.1.8.4(5)) 



1.3 EXITING FROM TECO 

One may exit from TECO by typing the EQ command (followed by 
and a newl ine) . 



1.4 TECO DEFINITIONS 

A. TECO uses four storage areas: 

(1) The buffer is the area where text to be edited is examined 
and modified. At all times it contains a (possibly null) 
character string. There is a pointer into the buffer, 
denoting the current position. This pointer does not point 
to a character; it points between two characters. The 
pointer may assume any value between 0 and Z, where "Z" is 
the number of characters currently in the buffer, 0 
indicates that the pointer is to the left of the first 
character, and Z would represent the position to the right 
of the lasL character in the buffer. The value of the 
pointer is represented by 

(2) Commands to TECO are written as a character string which 
is read into the Command String Area . TECO interprets the 
characters in the command string as a series of commands. 
Upper and lower case letters may be used interchangeably 
in commands. 

(3) The Q-Reg i sters are locations for storing either numeric 
quantities or strings of text for later use. Each 
Q-Register is designated by a single character name. There 
are 95 Q-Registers, one for each printing ASCII character. 
Each Q-Register may contain a positive or negative integer 
or a character string. 

(4) The G-P.egister pushdown list Is a 1 as t- i n-f i rs t-ou t (LIFO) 
list which may be used to temporarily store the contents 
of a Q-Register. It is cleared (i.e., the contents are 
lost) every time one returns to command level, i.e., a "E" 
is typed. 
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B. TECO uses numer i c express ions for many of its operations. 

Tliese may consist of any combination of decimal or octal 
numbers^ the unary operator "-"^ tlie binary operators "+"/ 
11.11^ ii/i.^ Mitt (boolean or), (boolean and), and 

the special valued commands and symbols. All operators are 
of equal precedence and expressions are evaluated from 
left to right. Note/ however, that parentheses may be 
used in their normal manner. Spaces are ignored (except 
to terminate decimal numbers). if two numeric quantities 
are given with no operator between them, the default 
operator is used. Note that a string of digits 

followed immed iatel v by a "." is interpreted as an octal 
rather than a decimal number. Division using the "/" 
operator is integer division, i.e., the remainder is 
ignored. The special symbols allowed in an expression at 
any point are: 



B (JBeginning) equivalent to 0 

Z equivalent to the number of characters in the 
buffer 

( point er) equivalent to the number of characters 
to the left of the pointer, i.e., the current 
value of the pointer. 



There is another special symbol related to the 
symbols above and this is the H (wHole) symbol. This 
symbol is equivalent to "0,Z". It is the only symbol in 
TECO that has two values. It is useful for referring to 
the whole buffer. 

Commands which return values may also be used in 
expressions, but they may not appear immediately to the 
right of an operator. This is because the command will 
assume that everything to its left is part of one of its 
arguments. If a command appears within parentheses, it 
will assume that its arguments are entirely between the 
last "(" and the command. Therefore a command will not 
read parts of an expression wich are outside the 
parentheses in which it appears. 

The plus and minus binary operators (excluding the 
unary minus) assume a right operand of 1 if none is given. 

EXAMPLES 



Assume that the current value of the pointer is 500. 
express i on va lue 

(1) (7 12)/3 - 6 

(2) 9+ = 10 

(3) b- = -1 
(h) - = -1 

(5) 1^ + 8/2 = 6 

(6) 101. = 65 



j teco 
I 
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(7) 3110 = 11 

(8) 1++++ ++ +++ + =11 

(9) 9*-2 = -18 

(10) 9*— 2 * 18 

(11) .10 = 510 

(12) 10. = 8 



C. Quoted strings are strings of text delimited by a quoting 

character. The quoting character may be anv character not 
contained in the string except a letter or a digit. The 
contents of a Q-register may be used as a quoted string if 
the letter "q" followed immediately by the letter 
specifying the Q-reglster is typed instead of the first 
quoting character. 

(See section 3.1.4) 

F?^AMPUS 

(1) "hello" 

(2) /This is a quoted string/ 

(3) ,This string is delimited by the comma character and 
contains 2 new-line characters. 

ik) ql 



1.5 ERROR MESSAGES 

TECO types out error messages in one of two modes, long or 
short. Short error messages are less than 9 characters long while 
long error messages are less than 50 characters long. The default 
mode is short. To change the error mode TECO is using, give the 
following Multics command: 

teco$ teco_error_mode long 
or teco$ teco_error_mode short 

if a short error message, such as "/ : ?" cannot be 
understood, the following Multics command will type out the long 
error message: 

teco_error "/ : ?" 

The above holds for all error messages except those 
informing the user that a file could not be found. 



l.e ! MPLEMENTAT I ON RESTR .' CT ONS 

The maximum number of characters allowed in a Q-register is 
2621t+3. The maximum number of characters allowed in a quoted 
string is 2621^^3, as is the maximum number of characters in a 
TECO command line. Note that these sizes are all one segment 
long. V\fhen the Multics segment size changes, these restrictions 
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will also change. The maximum number of items in the pushdown 
list is 20. The maximum depth of macro calls is 20. The maximum 
depth of parentheses is 20. 



1.7 LEARNING TECO 

This manual contains three logical sections. In the first 
section (Chapter 2) commands are described which: 

(1) read and write files 

(2) examine text within a file 

(3) make deletions and insertions 
ih) search for strings of text 

Examples of using the commands are given at the end of the 
chapter. After reading Chapters 1 and 2 the reader should be 
able to use most of the common editing requests. 

In the second section (Chapter 5), more sophisticated TECO 
commands are described^ including use of Q-registers, macros, 
iterations/ conditionals. The commands listed in chapter 3 
transform TECO from just another editor to one of the most 
powerful general purpose text editors in existence. 

The third section contains a summary of all the TECO 
commands in alphabetical order. This is intended to be used as a 
reference section. 
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CHAPTER 2 
BASIC TECO COMMANDS 



2.1 The most general form of a TECO command would be: 
m^nX/string/ 

where m and n are optional numeric arguments^ X Is the command to 
be executed/ and /string/ Is a quoted string. In most cases the 
command will be just one character, though In some cases it may 
be two characters. Not all of the commands take arguments. Those 
that do generally have default values for missing arguments. 
Only a few commands expect quoted strings. The string must not be 
omitted If the command expects one. Some commands also return 
values, this will be discussed in Chapter 3. 

The letter chosen for a command generally has some mnemonic 
meaning, which Is indicated In the description of the command. 
Unfortunately, TECO has a fairly long history, having originally 
been developed for editing paper tapes, and so some of the 
mnemonic meanings are almost lost now. As many commands as one 
wishes may be typed at a time. Execution of the commands will not 
start until after the "$" followed by a newl ine character Is 
typed. Spaces may be Inserted anywhere (except In the middle of 
numbers) and newl ine characters may be inserted anywhere except 
between a command and its arguments. 

Remember that upper case and lower case letters may be used 
interchangeably as commands. 

2.1.1 ENTERING TECO 
See section 1.2. 



2.1.2 READING A FILE ; - El (External Input) 



El/pathname/ reads in the file specified by pathname, 

which is assumed to be a standard Multlcs 
pathname. The contents of the file are 
inserted in the buffer at the current pointer 
position and then the pointer Is moved to the 
right of the text just inserted. 



2.1.3 WRITING A FILF ; - EO (External Output) 

EO/pathname/ writes the contents of the buffer to the file 

specified by pathname. This command takes 
arguments similar to the "T" command; It 
writes out that part of the buffer which 
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would be typed by "T". Note/ however^ that 
if Qo arguments are given, "EO" assumes "B^Z" 
as the default rather than "1". 
Note: The pointer is never moved by the "EO" command. 

l.l.k TYPING THE BUFFER - T (lype) 

T equivalent to "IT" 

nT +n types out the string of characters beginning 

at the current pointer position and 
terminating after n newline characters have 
been encountered. T types out the rest of the 
current 1 ine, and 2T types out the rest of 
the current line and the next line. The last 
character typed by T is a newline unless 
there aren't that many lines in the file, 
-n types out starting just after the (n+l)th 

newline to the left of the pointer and 
finishing at the pointer. OT types out the 
beginning of the line up to the current 
pointer. Usually two T commands are given at 
once/ such as OTJ , which types out the entire 
line the pointer is in, V/hen OT is useful, 
the last character it types out is not a 
newline. -T types out the previous line and 
the beginning of the current line. If the 
pointer is at the beginning of a line, -T 
types out the previous line, the newline at 
the end of that line/ and nothing more. 

m/nT Types out the (m+l)th through the nth 

characters of the buffer. 
Note: The pointer is never moved by the "T" command. 

2.1.5 MOVING THE POINTER - J Uump)/ C (Characters), R (Reverse), 
and L (i.ines) 

nJ Moves the pointer to the right of the nth 

character in the buffer, i.e., sets "." to 
the value of n. If n is not specified, 0 is 
assumed. That is, the pointer is moved to the 
left of the first character in the buffer. 

nC Moves the pointer n characters to the right 

of its current position (equivalent to .+nJ). 
If n is omitted/ 1 is assumed. 



nR 



Like nC except it moves the pointer to the 
left (equivalent to -nC). If n is omitted, 1 
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is assumed. 



nL +n Moves the pointer to the right/ stopping 

after it has passed over n newline 
characters. If n is omitted, 1 is assumed. L 
moves the pointer to the beginning of the 
next 1 ine . 

-n Moves the pointer to the left/ stopping after 

it has passed over n+1 newline characters and 
then moving it to the right of the last 
newline character passed over. OL moves the 
pointer to the beginning of the current 1 ine, 
and -L moves the pointer to the beginning of 
the previous 1 Ine. 

:L (See section 3.1.1) 



2.1.6 DELETING TEXT - D (Delete) and K (£111) 

nD Deletes n characters. If n is positive the 

characters are deleted to the right of the 
pointer. If n is negative the characters are 
deleted to the left of the pointer. If n is 
omitted/ 1 Is assumed. 

K Takes arguments like the "T" command except 

that it deletes that text which "T" would 
type. The pointer is moved to where the 
deletion took place. If no arguments are 
specified/ "IK" Is assumed. 

+n deletes all the characters beginning at the 

current pointer position and terminating 
after n newline characters have been 
encountered. K deletes the rest of the 
current line and the newline character at the 
end of the Mne, while 2K deletes the rest of 
the current line and the next line, 

-n deletes all the characters starting just 

after the (n+l)th newline to the left of the 
current pointer and ending at the current 
pointer. OK deletes the beginning of the 

current line without deleting the newline 
character at the end of the previous line. -K 
deletes the previous line and the beginning 
of the current line. To ensure that only the 
previous line is deleted/ the command 
sequence "OL-K" can be used. 



Deletes the (m+l)th through 
characters of the buffer. 



the 



nth 



MULT ICS PROGRAMMERS* MANUAL 



teco 



Page 9 



2.1.7 INSERTING TEXT - I (Insert) 



I/text/ 



Inserts the text of the quoted string at the 
current pointer position and moves the 
pointer to the right of the inserted text. 



nl Inserts the character whose ASCII code value 

is n. It moves the pointer to the right of 
the inserted character. 

: i (See section 3.1.3.2) 



2.1.8 SEARCH FOR TEXT - S (^earch) 
S/string/ equivalent to IS/string/ 

nS/string/ Searches for the nth occurrence of the quoted 

string. If n is positive the text is searched 
from the current pointer through the end of 
the buffer for the nth occurrence of the 
string. If found/ the pointer is set to the 
right of the matching string. Otherwise the 
pointer is not moved and an error message is 
typed. If n is negative the text is searched 
from the current pointer position to the 
beginning of the buffer for the nth 
occurrence of the quoted string. The pointer 
is set to the left of the matched string. If 
the string is not found the pointer is not 
moved and an error message is typed out. 



m^nS/string/ Instead of searching the entire buffer for n 

occurrences of the quoted string, only m 
lines from the current pointer are searched. 
If m is positive/ the only part of the buffer 
that will be searched will be from the 
current pointer to just after the mth newl ine 
character after the current pointer. If m is 
0 or negative/ the only part of the buffer 
that will be searched will be from the 
current pointer to just after the (m+l)th 
newl ine before the current pointer. 
1/lS/text/ will only search the rest of the 
current line. 0/-lS/text/ will only search 
the beginning of the current line. If m is 
less than or equal to 0/ n must be negative. 
If m is greater than zero, n must be 
pos i t i ve. 



:S/string/ 



(See section 3.1.1) 



teco 
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2.1.9 TYPING OUT VALUES - = (Equals) 

n~ o£ m/n= types out the decimal value of all the 

arguments separated by spaces and ending with 
a newl Ine. 



2.1.10 LEAVING TECO - EQ (£xternal ^uit) 

EQ returns to the caller of TECO (e.g./ Multlcs 

command 1 evel ) 
Note: don't forget to do an EO command before the EQ. 



2.1.11 RESTARTING TECO AFTER A "QUIT" 

If one "quits" out of TECO in order to abort a command 
string, one may use the "program_interrupt" ("pi") command to 
restart TECO. It will not abort the entire command string; only 
those commands which have not yet been executed. The current 
command is aborted if the effect of doing so would be Identical 
to that of not starting the command in the first place. TECO 
keeps track of what it Is doing, so that If the sequence: 

(quit) 

program_lnterrupt (or "pi") 

is given, it will not abort the current operation if it would 
leave TECO in an inconsistent state. In other words, the sequence 
will only interrupt between TECO commands, not In the middle of a 
command. 

At times it is desirable to get around this feature. When 
doing an "EO", for instance, TECO will not allow the user to "pi" 
back to TECO command level once the EO has started until it has 
completed writing the file. To get around this, one should type: 

(quit) 

teco$abort or TECO$ABORT 

When TECO$ABORT is called, the most recent invocation of 
TECO aborts its current operation without checking for 
consistency of states. Note that TECO will be in a consistent 
state whenever it actually accesses a file, and so there should 
be no problems encountered if this feature is used to get out of 

a runaway "E" command. Under other circumstances, however, it is 
wise for the user to type: 
-5t5t 

to make sure that things are OK. Except for the case of a runaway 
EO command, this feature is probably totally unnecessary in 
normal use. 
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2.2 STAND-ALONE EXAMPLES 

2.2a MimiM im 

a) teco source. pi 1 

b) TECO <x>y>z>a.ec 

c) teco 

2.2.3 READING A FILE 
a) E I /source. pi 1/ 

2.2.5 WRITING A FILE 

a) EO/new_source .pi 1/ 

b) .,2E0/bottom/ 

c) 2E0/nnes/ 

2.2.4 TYPING TEXT 

a) 2T 

b) OT 

c) OTT 

d) 25,100T 

2.2.5 MOVING THE POINTER 
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enter TECO and read In the file 
source.pl 1 from the working 
d! rectory. 

enter TECO and read in the file 
specified. 

enter the buffer initially empty. 



Insert the text contained in 
source.pl 1 at the current point in 
the buffer. 



VIrite the whole buffer out into 
new_source.pl 1. 

Write out the buffer from the 
current pointer to the end into the 
file "bottom". 

Write out two lines starting at the 
current pointer position to the 
file "lines". 



Type out from . to the end of the 
next 1 ine . 

Type out the current line from its 
beginning to ".". 

Type out all of the current line. 

Type out the 25+1 (26th) through 
the 100th character of the buffer. 



a) J 



Position the pointer at the 
beginning of the buffer. 



; teco ' 

i - 

! 1 
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b) ZJ 

c) L 

d) OL 

e) -L 

f) R 

g) 812-388C 

2.2.6 DELETING TEXT 

a) 19,22K 

b) 19J 3D 

c) HK 

d) -D 

2.2.7 INSERTING TEXT 

a) I/abc 
/ 

b) I .abc . 

c) 651 
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Position the pointer at the end of 
the buffer. 

Position the pointer at the 
beginning of the next line in the 
buffer. 

Position the pointer at the 
beginning of the current line. 

Position the pointer at the 
beginning of the current line. 

Back up the pointer by one 
character position. 

Move the pointer ahead 812-388 
iklk) character positions. 



Delete the 19+1 (20th) through the 
22nd character of the file. Set the 
pointer to 19. 

Move the pointer to the right of 
the 19th character and then delete 
the next three characters (20-22). 

Delete the whole buffer. 

Delete the character just to the 
left of the pointer. 



Insert the line "abc" followed 
by a new-1 ine character at the 
current pointer position. 

Insert the string "abc" without a 
new-line character. 

Insert the character with ASCII 
code 65 ("A") at the current 
pointer position. 
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2.2.9 TYPING VALUES 

a) Z = 

b) Z^.= 

c) = 

d) Q6+53 = 



Type out how many characters are In 
the buffer. 

Type out how many characters are in 
the buffer followed by the current 
pointer position. 



Type just a blank line. 

Type out 53 d1 us the 
contained in Q-register 6. 



value 



2.2.8 SEARCHING FOR TEXT 

a) J S/Hello/ 

b) ZJ -S"Heno" 



c) J 3S"* 
II 



d) J l^lS/hel lo 
/ 



Position the pointer just to the 
right of the first occurence of the 
string "Hello" in the buffer. 

Position the pointer just to the 
left of the last occurence of the 
string "Hello" in the buffer. 

*• 

Position the pointer just after 
the third occurence of a line 
ending with a "*". 



Position the pointer just after 
the first line in the buffer if it 
ends in "hello". If the first line 
does not end in "hello" type out an 
error message. 
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2.3 EXAMPLES O F BASIC EDITING REQUESTS 



Note: In the following examples^ underlined text is produced by 
TECO. 



TECO abc.pll 
I5LT$ 

del a fixed bin: 
lS/a/-DI/b/OLT$ 

del b fixed bin; 

fiS/dcl d/OLKT$ 



del f fixed bin: 
IKI/dcl g char(2); 

/$ 

lEO/abc.pll/EQ$ 



Enter TECO and read in the segment 
abc.pl 1. 

Move to the 6th 1 ine and type it 
out . 

Change the "a" to a "b" and retype 
the 1 ine. 

Search for the declaration of d and 
delete the line that contains it. 
Then type out the next line. 



Delete this line and then insert a 
declaration of g. 

Write the edited text out to the 
file and then return from TECO. 
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CHAPTER 5 
ADVANCED TECO COMMANDS 



3.1 In Chapter 2 the general form of a TECO command was given. 
Some items were left out^ however. The actual format is: 

m, nXq/str ingl//str ing2/ . , . /str ingn/ 
The q indicates a Q-register on which the command is to act. 

It should also be noted that more than one string may be 
given. Although no TECO command currently accepts more than one 
quoted string/ a macro may be called with multiple string 
arguments which may be retrieved inside the macro by the :X 
command. 

In Chapter 1 we specified that expressions may be built from 
numbers, special valued commands and symbols. Examples of valued 
commands will be given in Chapter 3. Care should be taken to 
notice that commands with values may appear only on the left side 
of the first operator/ or within parentheses. Otherwise the part 
of the expression preceding the command will be considered an 
argument to the command. 



3.1.1 The effect of many commands may have their function 

changed by preceding the command with a The colon has no 

fixed meaning - it is defined for each command individually. The 

following commands given earlier may be used as follows. 

:lq/string/ or n:lq like the I command except that the specified 

string is inserted into Q-register q. The 
former contents of Q-register q are lost. 

n:L Equivalent to nLR. Thus TECO moves to the end 

of the line rather than the beginning. 

:S/string// n:S/string// or m/ n :S/ str i ng/ like S except that it 

returns a value. The value is 0 if the search 
fails and -1 if it succeeds. Even if the 
search fails, TECO continues execution. 

:T/string/ types the specified string on the user's 

console. 

:vw (See section 3.1.10) 



:x 



(See section 3.1.8.3) 
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3.1.2 Numeric Q-Registers 

Q-Registers may be used/ as mentioned in section 1.^*/ to 
hold numeric values. These values may be used in expressions 
which are arguments to other commands. 

3.1.2.1 SAVING A VALUE - U (Update (or what comes after Q? ) ) 

Uq sets Q-register q to a very large positive 

number, 

nUq sets Q-register q to n. 

m^nUq sets Q-register q to n and returns m as its 

val ue . 



3.1.2.2 READING Q-REGISTERS - Q (^-Register (Don't ask me why 
"Q")) 

Qq Return the number stored in Q-register q as 

the value. Note that Q is not really a 
command - it is a special symbol (as in 
section 1.U.2). Thus^ in the expression 
"5+Q3" the "5+" is not considered an argument 
to Q; the result is the sum of Q3 and 5. Note 
if Q-register q contains text/ the length of 
the text in characters is returned. 



5.1.2.3 INCREMENTING Q-REGISTERS - % (You figure out the 
mnemon i c ) 

%q Add 1 to Q-register q and return the new 

number as the value. Q-register q may not 
contain text. Note that like Q/ is a 

special symbol/ not a command. 



3.1.3 Text Q-Registers 

Q-Registers may also be used to hold character strings. They 
may be used to move text from one place in the buffer to another/ 

to save command lines for execution as macroS/ or to provide 
quoted strings for commands which expect them. 

3.1.3.1 EXTRACTING TEXT TO A Q-REGISTER - X (eXtract) 

Xq takes arguments like the "T" command/ but 

copies the text that T would type into 
Q-register q. The former contents of 
Q-register q are deleted. The text is not 
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deleted from the buffer and the current 
pointer is not moved. 

nXq +n copies all the text from the current pointer 

to just past the nth newHne character to the 
right of the pointer into Q-register q. XI 
copies the rest of the current line including 
the new! ine at the end of the line into 
Q-register 1. 2Xa copies the text on the rest 
of the current line and all of the next line 
into Q-register "a", 
-n copies all the text from just to the right of 

the (n+l)th newline that is to the left of 
the current pointer to the current pointer 
into Q-register q. OX/ copies the beginning 
of the current line into Q-register "/". No 
newline characters will be put into 
Q-register "/". -Xa puts the previous line 
and the beginning of the current line Into 
Q-reglster "a". 

m^nXq copies character number (m+1) through 

character number n Into Q-register q. 

:X (See section 3.1.8.3) 



3.1.3.2 INSERTING TEXT DIRECTLY INTO A Q-REGISTER - :l linsert) 

:lq/string/ This command is identical to the normal "I" 

command except that the text is inserted Into 
Q-register q rather than the buffer. The 
former contents of Q-register q are deleted. 
The main text buffer is not affected. 

n:lq Is like :l except that It puts the character 

corresponding to n into the Q-reglster q. 



3.1.3.3 GETTING TEXT FROM A Q-REGISTER - G (Get) 

Gq inserts the text contained in Q-register q 

into the buffer to the left of the current 
pointer. If the Q-register contains a number, 
the decimal representation of the number Is 
inserted. 



3.1.** Obtaining quoted strings from Q-registers. 



VJhenever TECO expects a quoted string, it is possible to 
indicate that the string Is in a Q-register. Normally letters 
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and digits are considered Illegal quoting characters, \f, 

however^ the letter "Q" is found where a quoted string is 

expected, the next character after the Q will be considered a 

Q-register name. Whenever a quoted string Is retrieved by any 

command/ it is loaded into Q-register As an example, SQ" 
immediately after another search will search again for the same 

string. This notation is Illegal If the specified Q-register 
contains a number. 



3.1.5 The Q-reglster pushdown stack. 

There Is one Q-reglster pushdown stack ( not one per 
Q-register) In which the values of Q-reglsters may be saved. It 
is organized as a pushdown (Last-in, First-Out) list. It is 
emptied every time TECO waits for a new command string. I.e., a 
"a" is typed, 

3,1,5,1 PUSHING A VALUE ONTO THE STACK - C (opposite of 3) 

Cq pushes the current value of Q-register q onto 

the top of the stack. The Q-reglster is not 
affected. 



3.1.5.2 POPPING A VALUE FROM THE STACK - ] (opposite of D 

]q pops the top value on the stack Into 

Q-reglster q. The previous contents of the 

Q-reglster are lost. It Is an error to do a 
"3" command If the stack Is empty. 



3.1,6 Loops 

TECO has the ability to execute a command string repeatedly, 
much as Fortran or PL/1 provides "do-loops", 

3,1,5.1 BEGINNING A LOOP - < and > (opposite of each other) 

< is equivalent to n< except that n Is set to a 

ve rv big number which Is for all practical 
purposes Infinite. 

n< causes TECO to take note of the fact that a 

loop is beginning. The value of n and the 

position of the "<" In the command string are 
saved . 

> causes execution to return to just after < if 

the string has not yet been executed n times. 
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n< , . . > 



this causes 
brackets to 



the string 
be executed n 



between 
t imes . 



the angle 



3.1.6.2 

it) 

n; 



TERMINATING A LOOP BEFORE n EXECUTIONS 



(think about 



If n is less than 0 then nothing is done. 
Otherwise execution of the current loop is 
aborted and TECO skips to just after the 
closing >. If n is not specified/ the result 
of the most recent S command is used 
(terminate loop if search failed). The ; 
command may not appear outside of a loop. 



3.1.7 Goto's 

TECO provides the ability to 
part of the command string. 

3.1.7.1 GOTO - 0 (goto) 



transfer control to a different 



0/str ing/ 



causes TECO to search the current macro (or, 
if we are not in a macro, the command line) 
for the string "'string!". If it is found, 
TECO begins interpreting commands just after 
the label found. If not found, but execution 
is currently in a macro, the search is 
repeated in the previous execution level, 
i.e., the caller of the macro. This is 
repeated until TECO has checked all the way 
down to the command line typed by the user. 
Note that although TECO may exit a macro 
using an 0 command, it may not use that 
command to exit a loop. Only ";" may be used 
to terminate a loop. 



3.1.8 Macros 



TECO has the ability to execute strings of text (macros) 



other than those read from the 
commands are: 



user's console. The associated 



3.1.8.1 EXECUTING A MACRO IN A Q~REGISTER - M (Macro) 



Mq 



causes the contents of Q-register q to be 
executed as a command string. Note that if 
the M command is given any numeric arguments 
they are passed to the first command inside 
the macro. String arguments may be fetched 
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by the :X command. 



3.1.8.2 EXECUTING A MACRO IN A FILE - EM (£xternal Macro) 

EM/string/ Is just like the M command except that the 

command string is found in a file named 
"str i ng. teco". This file is looked for in 
three places: 1) the working directory, 2) 
the user's login directory, 3) the TECO 
library. TECO$teco__ssd is a command that 
takes a single argument, an absolute pathname 
for a search directory, and changes the TECO 
search rules so that instead of searching the 
user's login directory, the search directory 
specified is searched. TECO$teco_search is an 
external subroutine (See section 3.1.16) that 
follows the same search rules used to find a 
macro . 

5.1.8.3 OBTAINING A STRING ARGUMENT TO A MACRO 

:Xq causes TECO to suspend execution of the 

current macro, return to its caller to fetch 
a quoted string into Q-register q, and then 
restore the macro that was being executed. 
Note that each :X command in a macro fetches 
another quoted string. Note that the U 
command (s) should be the first command in a 
macro if one wishes to fetch numeric 
arguments In a macro. 



3.1.8.t* A few notes about macros: 

1) Loops may not cross macro boundaries, i.e., a loop may 
not start in one macro and end in another. This does 
not, however, prohibit the M command from being used 
within a loop. 

2) A macro may modify itself if it is in a Q-register. 
Note, however, that the current invocation of the macro 
will not be affected; only future accesses to the 
Q-register. If the macro is invoked by the EM command, 
the results of modifying the file are hard to predict: 
TECO reads the command string directly from the file. 

3) When a macro is invoked by the EM command it should be 
noted that the name of the macro will be found in the 
Q-register named ". Thus one can put several macros in 
one segment with the first command in the segment being 
OQ". (Doii't forget to put all the appropriate names on 
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the segment.) 

k) If an M or EM command Is given as the last command in 
one macro, the command Is interpreted as a goto rather 
than a call. Thus one may do unlimited M's in this 
manner although there is an implementation-defined 
limit to the depth of calls. 

5) When TECO Is entered, a macro named "start_up" is 
searched for. If It Is found, the arguments to TECO are 
put onto the pushdown stacl< and the start_up macro is 
executed. If no start__up macro is found, the string 
"E l/f 1 lename/ J" is executed, where filename is the 
first argument to TECO. At the present time there is a 
start_up macro in the TECO library. When the start_up 
macro Is called, the first thing on the pushdown list 
is the number of arguments TECO was called with. The 
remaining items in the list are the actual string 
arguments to TECO going from left to right on the 
command 1 Ine. 



3.1.8.5 CODING CONVENTIONS FOR MACROS 

Since there are only a small number of Q-registers (95), 
each with a one character name, there are serious problems in 
writing a set of macros that are compatible. A set of macros 
become incompatible if one macro uses a Q-register for long-term 
storage that any other macro uses at all. There are two ways 
this effect can be combated. First, by establishing certain 
coding conventions, and second, by use of a documented macro 
library. Probably the most important coding convention is the 
specification of which Q-registers may be used inside a macro for 
temporary storage. Many macro writers nov; use the ten Q-registers 
1, 2, 3 , i*, 5, 6, 7, 8 ,9, and 0 for temporary storage. If one macro 
wants to call another macro that will clobber one of these 
registers, the calling macro may save the value of the Q-register 
In the pushdown list and then restore it after the other macro 
has been called. 

Fortunately, calling a macro is a very inexpensive operation 
in TECO if the macro is in a Q-register. The EM command is much 
more expensive, however. This leads to the practice of creating a 
macro in a macro library that v;ill only load a Q-register with a 
useful macro. When the user realizes that he wants the macro, he 
gives the EM command that will load the macro he wants into a 
Q-register, where he may then call it whenever he wishes, it now 
becomes necessary to have coding conventions that specify which 
registers may be loaded permanently w'th macros. Since it should 
be easy to type the macro names, the lower case alphabetic 
letters should be used for this purpose. Sometimes a macro will 
use a Q-register for long-term storage. If the user will not have 
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to type the name of this Q-register, names that must be escaped 
on a 27kl are good/ otherwise other special characters may be 
used. This leaves the upper case alphabetic letters entirely to 
the user for him to use to store intermediate results in editing. 
Also the special characters "/"/ space^ tab, and 

newl ine should be reserved for the user since these are all lower 
case letters on both a 27hl and a Model 37 teletype. 

An extremely useful feature of TECO is that the last quoted 
string is loaded into Q-register To allow this to continue to 

be useful/ all macros should mal<e sure that Q-register " either 
contains the last quoted string argument to the macro, if there 
are any, or contains what it contained before the macro was 
called, Q-register " can be saved on the pushdown list on entry 
to a macro and then restored just before leaving the macro. Use 
of the pushdown list Is very inexpensive. 



3.1.8.6 RELATIVE COSTS IN TECQ 

TECO stores the buffer In two pieces. The first piece, all 
the characters from the beginning of the buffer to the current 
pointer, is stored at the beginning of one buffer segment, while 
the second piece, all the characters from the current pointer to 
the end of the buffer, is stored at the end of another buffer 
segment. An insert merely adds text to the end of the first 
buffer segment and Increases the number of legitimate characters 
in the first buffer segment. A D or X command merely changes the 
number of legitimate characters in one of the buffer segments. In 
order to move the pointer, a string copy from one buffer segment 
to the other must be performed. It does not matter to TECO which 
direction the pointer is moved, although a reverse search is 
somewhat slower than a forward search, since the PI 1 Index 
built-in function can only be used for a forward search. 

Any operation tiiat does not move text is less expensive than 
an operation that does move text, where the cost of the operation 
that does move text is proportional to the amount of text moved. 
For the most part, performing Input or output Is the major cost 
involved in editing. This cost can be decreased by using more 
sophisticated commands, such as loops or macros, and performing 
the same editing operation with fewer Interactions. The cost of 
i/o operations is comparable to a medium length search ( 5,000 
characters ). 

Each text Q-register is presently kept in its own segment. 
This means that If a start_up macro loads many Q-reglsters with 
macros, then entering TECO for the first time in a process will 
be somewhat slow since all these segments must be created. TECO 
has its own segment manager (get_temp_seg_) , that allows it to 
re-use segments without calling hardcore to create and delete 
segments when the values of Q-registers are changed. Whenever a 
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string is quoted^ or a Q-register loaded with text/ a new segment 
is retrieved from get_temp_seg_ and loaded with the value, if the 
string that is being loaded into the Q-register is in another 
Q-register, the new Q-register is just made to point to the same 
copy of the text in the first Q-register, :IAQB is therefore a 
very simple operation, as are C (Push) and J (Pop). The feature 
of keeping the last quoted string in Q-register " lets the user 
tal<e advantage of this scheme. 

If the user wants to write a macro that must do some editing 
on another file, it is much cheaper if he saves the value of 
and Z-. , inserts the text to be edited, edits it, writes it out 
or copies it into a Q-register, and then deletes what he was just 
editing from the buffer. The net change to the buffer by all 
these operations is zero, but the text that the user was editing 
was never moved. This method is much cheaper than storing the 
entire buffer in one Q-register, the value of the pointer in 
another, and then using the buffer for the editing within the 
macro. 

There are four ways to transfer control in TECO, by the > 
command, the ; command, the "or command, and the 0 command. 
Of these the > command is the fastest since TECO already knov/s 
exactly where to transfer to. The ;, ", and :* commands are next, 
since they merely search from where they are forward. Although 
the > command and the ; command cannot change macro levels, the 
and commands can. This adds a small expense. The ;, and 
commands all have to check so that a ; command will 
completely skip over another nested loop and look beyond it for a 
>, Similarly the " transfer will skip over nested if statements, 
as will the command. Usually the matching * or > is not far 
from the transfer, so this only causes a short search. 0 is the 
most general and most expensive transfer of control in TECO, It 
must search the entire macro from the beginning, then the entire 
macro that called the present macro, etc. until it finds it or 
finishes searching the command line and gives an error. Although 
this is the most expensive transfer, its cost is proportional to 
the distance of the label from the beginning of the macro. 



3.1.9 Conditionals 

TECO has the ability to conditionally execute strings. The " 
command corresponds to the PL/1 statement "if ... then do;" The * 
command corresponds to the PL/1 statement "end;". " and ' are 
matched much like ( and ) and may be nested. The letter following 
the " determines what test will be made. 



3,1.9.1 NUMERIC COMPARISONS - "E (Equals), "N (Not equal), "G 
(greater than),"L (L.ess than) 
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m,n"E If m=n then execution continues; otherwise 

execution sl<ips to just after the 
corresponding 

n"E identical to n,0"E. 

m/n"N like m/n"E except it tests for m"*=n. 

n"N Identical to n^O"N. 

m^n"G lii<e m,n"E except it tests for m>n. 

n"G identical to n,0"G. 

m/n"L 1 ll<e m/n"E except it tests for m<n. 

n"L identical to n,0"L. 

3.1.9.2 TESTING FOR A SYMBOL CONSTITUENT - "C (symbol 
C.onst I tuent) 

n"C if n is the ASCII code for either a letter, a 

digit or one of the characters "."/ "_"/ or 
then execution continues; otherwise 
execution skips to the corresponding '. 

3.1.9.3 TERMINATING A CONDITIONAL DO - * (matches ") 

* is ignored when executed in normal execution. 

It is used to close a conditional statement, 

:* This command causes a transfer to the next 

ust as a l"e does. Since this command looks 
like a \ it can serve to close a conditional 
statement. This is useful if an if ... then 
... else ... statement is desired. The if 
expression is a " statement/ the then 
expression is terminated by the :* command 
and the else expression is terminated by the 
' command. 

3.1.10 Reading input from the user's console. - VW (V then Wait 
for input) 

VW does a V command (presently does nothing on 

Multics) and then reads one character from 
the user's console. The ASCII value of the 
character is returned as the value of the 
command. Note that Multics escape/kill 
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processing Is not effected because only one 
character is read at a time. 

:VWq does a V command and then reads one 1 Ine from 

the user's console. The line is put into 
Q-register q. The newline is the last 
character read in. 



3.1.11 Passing a command to the command processor - EC (JExternal 
jQ.ommand) 

EC/string/ passes the specified string to the Multics 

command processor for execution. 



3.1.12 Examining a character in the buffer - A (Ascii) 

nA The ASCII code for the (.+n)th character in 

the buffer is returned as the value of the 
command, n must be specified. (Note that 1 
indicates the character just to the right of 
the current pointer, 0 indicates the 
character just to the left.) 



3.1.13 Tracing command execution - ? (Asking what happens) 

? turns tracing on. VJhen tracing is on, each 

command executed by TECO is printed on the 
user's console just before it is executed. 

?? turns off tracing. 



3.1.1U Translating numbers to ASCII and vice versa - <J: (You 
figure it out) 

^ reads the decimal number found to the right 

of the current pointer and returns its value 
as the value of the command. The pointer is 
moved to the right of the number. The number 
may be signed and may be preceeded by any 
number of blanks or tabs. It Is an error if 
no number is found. 

n<^ inserts the decimal interpretation of n into 

the buffer to the left of the current 
pointer. 



m, n(J: 



inserts the decimal interpretation of m into 
the buffer to the left of the current 
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pointer. The interpretation is padded on the 
left to be at least n characters wide. 



3.1.15 Null command - W (Wipe out?) 

\'i does nothing. It is most useful for throwing 

away unneeded numeric arguments. 

new_line has the same effect as W, 

$ has the same effect as VI, 



3.1.16 Subroutines 



TECO has the ability to communicate with programs written by 
users on Multics. In particular^ TECO macros can get information 
from programs written to interface with those macros. 

3.1.16.1 CALLING A SUBROUTINE - ES (External Subroutine) 

m, nESq/prog__name/ prog_name is a relative pathname of a segment 

with an optional entry point name. The search 
rules are used to find the segment. The entry 
point specified is called in the following 
way: del prog_name ext entry (char (*) 
aligned/ fixed bin, fixed bin, fixed bin); 
call prog_name (CL.regl ster, m, n, value); q 
must be a text Q-register. prog_name will be 
called with the Q_register as the first 
argument. If this string is changed, the 
(L.register will be changed. This command has 
a numeric value that can be set by changing 
the fourth argument to prog_name. This is 
initialized to zero. If the ES command is 
called with one numeric argument, it will be 
passed as the second argument to prog_name 
and the third argument will be a very large 
positive number. If no numeric arguments are 
given to ES, both the second and third 
arguments to prog^name will be very large 
posi t ive numbers. 



3.1.1 6.2 A few notes about subroutines: 



1) TECO$teco_search is an external subroutine that can be 
used. It takes a Q-register that contains the name of 
an external macro followed by a blank followed by 
enough characters to hold an absolute pathname in the 
whole register. TECO$teco_search searches for the macro 
(it adds ".teco" to the name) using the TECO search 
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rules. If it Is not found it returns with the value 0. 
If It is found, it changes the Q-register to hold an 
absolute pathname to the macro followed by enough 
blanks to fill up the Q-reglster/ as long as it is not 
longer than 256 characters. The value returned is the 
number of non-blank characters at the beginning of the 
Q-register. 

2) TECO$teco_no_ES is an entry point in TECO that is very 
similar to the main entry point of TECO, except the ES 
command is not an implemented feature of 
TECO$teco_,no_ES. This entry point is meant to be used 
by subsystems that cannot allow a user to make a call 
to an arbitrary procedure. 
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3.2 EXAMPLES OF MACROS 
3.2.1 A WRITING MACRO 

This macro writes out the entire buffer into a file whose 
name is in Q-register *. The file being edited can be changed 
merely by doing : i */new_name/ . 

EOQ* This macro assumes that the name of the file 

we are editing Is In Q-register *. It writes 
out the entire buffer into this file. 



3.2.2 A RESTART MACRO 

This macro zeroes out the buffer, changes Q-register * to be 
a new file name and reads the file into the buffer. 

:x* hk eiq*j 

:X* This macro takes one string argument and 

loads it into Q-reglster *. 

HK Since we are restarting the editing, we 

delete all the text in the current buffer. 

EIQ*J We now read the new file into the buffer and 

put the pointer at the beginning of the 
buffer. 



3.2.3 A START UP MACRO 

This macro only uses the first argument to TECO. It treats 
It as a file name, loads it into Q-register * and reads the file 
Into the buffer. It also loads the writing macro Into Q-reglster 
w. 

jl :lw|eoq*| ql"n 3* eiq*j * 

11 Pop the top item off the pushdown list and 

put It Into Q-register 1. This will be the 
number of arguments TECO was called with. 

:iw|eoq*| Load Q-reglster w with the writing macro 

given in Example 3.2.1. 

ql"n If the contents of Q-register 1 are not zero, 

then execute the following statements, 
otherwise transfer to the ' that ends the 
macro. 
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1* Pop the first argument to TECO off the 

pushdown list and into Q-register *. 

eiq*j Read the file into the buffer and move the 

pointer to the beginning of the buffer. 

* This point is transferred to if there are no 

arguments given to TECO. 



3.2.1* A SUBSTITUTE MACRO 

This macro takes two string arguments. The first string 
argument is searched for^ then it is deleted and the second 
string inserted. 

:xl :x2 sql -qld g2 

:xl Load the first string argument into 

Q-regi ster 1. 

:x2 Load the second string argument into 

0.- register 2, 

sql Search for the first string. 

-qld Delete the first string when it is found. 

g2 Replace the string found with the second 

string argument. 

When the macro returns^ Q-registers 1 and 2 contain the 
first and second strings/ respectively. Q-register " contains the 
second quoted string. 
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CHAPTER k 
A TECO SUMMARY 

NAME MNEMONIC SECTION USE EXPLANATION 

a Ascii 3.1.12 nA The value of the command is the ASCII 

code for the (.+n)th character in the 
buffer. 

b beginning l.UB B The value of this symbol is always 

zero. 

c Characters 2.1.5 nC Moves the pointer n characters to the 

right. If n is omitted/ 1 is assumed. 

d delete 2.1.6 D deletes the one character to the right 

of the pointer. 
+nD deletes n characters to the right of 

the pointer. 
-nD deletes n characters to the left of 

the pointer. 

ec E.xternal C.ommand 3.1.11 EC/command/ passes the string to the 

Multics command processor. 

ei External Input 2.1.2 El/file/ reads the file into the buffer 

to the left of the current pointer. 

em JExternal Macro 31 3,8.2 EM/macro__name/ searches for the file 

"mac ro_name. teco"/ first in the 
working directory/ then the login 
directory, then the TECO library. If 
found- It executes i t as a macro. 

eo External Output 2.1.3 EO/f i 1 e_name/ writes out the entire 

buffer into the file specified. 
+nEO/f i le_name/ writes out the next n lines. 
(0 or-n) EO/f i 1 e_name/ writes out the last n lines. 

m, nEO/f i le_name/ writes out the (m+l)th through the nth 

characters , 

eq External £uit 2.1.10 EQ TECO returns to its caller after 

zeroing out all Q-registers. 

es E.xternal Subroutine 3.1.16 m, nESq/prog_name/ Calls subroutine 

progname with arguments Q-register 
m, n, value. The numeric value of the 
command is set by prog__name and the 
contents of Q-register q may also be 
changed. 
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NAME MNEMONIC SECTION USE EXPLANATION 

g £et Q-register 3.1.3.3 Gq inserts the text contained in 

Q-reglster q Into the buffer to the 
left of the pointer. If Q-register q 
contains a number^ it is converted to 
a character string and Inserted. 

h wMole l,kB H This symbol is equivalent to 0,1 . It 

is the only symbol that has two 
va 1 ues . 

I Insert 2.1.7 I/string/ Inserts the quoted string to the left 

of the pointer, 
nl n Is the ASCII code for a letter that 
Is Inserted. 

:i 3.1.3.2 :lq/string/ inserts the quoted string into 

Q-register q. 
nrlq Inserts the single character whose 
code Is n into register q, 

j jJump 2.1.5 nJ moves the pointer to the right of the 

nth character in the buffer. If n is 
omitted, 0 Is assumed. 

k J<ill buffer 2.1.6 K deletes the rest of the current line 

from the buffer. 
+nK deletes the next n lines from the 
buffer. 

(0 or-n)K deletes the last n lines from the 
buffer. 

m,nK deletes the (m+l)th through the nth 
characters from the buffer. 

1 J-ines 2,1.5 L moves the pointer to the beginning of 

the next 1 Ine. 
+nL moves the pointer to the beginning of 
the next nth 1 I ne. 
(0 or-n)L moves the pointer to the beginning of 
the last nth 1 Ine. 

:1 3.1.1 :L moves the pointer to the end of the 

current 1 i ne . 
+n:L moves the pointer to the end of the 
next (n-l)th 1 ine. 
(0 or-n):L moves the pointer to the end of the 
last (n+l)th line. 



m Macro 3.1,8.1 m, nMq/s tr i ngl//st r i ng2/ . . . /st r i ngn/ starts 

executing the text in Q-register q as 
a macro, m and n are numeric 
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arguments to the first command in the 
macro. stringl through stringn are 
string arguments to the macro that can 
be retrieved with the :X command, EM 
also takes all these arguments. 



o g£to 3.1.7.1 o/label/ transfers control to just after Mabel I 

in the current macro, its cal ler, 
etc./ or the command string. 



^-register l.^^C Qq 



the value of this command is the value 
of Q-register q if it is a numeric 
Q-register or the number of characters 
in Q-reglster q if it contains text. 
This command can also replace any 
quoted string if Q-register q contains 
text. The contents of the Q-register 
are used as the quoted string. (See 
also sections 3.1.2.2 and 3.1.^*) 



Reverse 2.1.5 



R moves the pointer one character to the 
left. 

nR moves the pointer n characters to the 
left. 



S.earch 2.1.8 S/string/ searches from the current pointer to 

the end of the buffer for "string", if 
found It moves the pointer to the 
the string. 



poi nter 

right of 

+nS/string/ searches for n occurrences of the 
string. Moves the pointer to the right 
of the nth occurrence. 
-nS/string/ searches for n occurrences of "string" 
from the current pointer to the 
beginning of the file. If found, 
moves the pointer to the left of 
nth occurrence. 



it 
the 



ne 



+m, +nS/s tr I ng/ only searches from the current pom 
to the beginning of the next mth li 
(0 or-m),-nS/str Ing/ only searches from the current poin 

to the beginning of the last mth line. 



:s 3.1.1 Takes arguments In all the ways S 

does, except that if S does not find 
the string it types out an error 
message and returns to TECO command 
level. :S does not. Instead, :S has 
the value -1 if the search succeeds 
and 0 if the search fails. 
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t Jype 2,1.4 T Type out the rest of the current line 

on the console. 
+nT Type out the buffer from the current 
pointer to the beginning of the next 
nth 1 ine . 

(0 or-n)T Type out the buffer from the beginning 
of the last nth line to the current 
pointer, 

m,nT Type out the (m+l)th through the nth 
characters of the buffer. 

:t 3,1,1 :T/strlng/ Type out the quoted string on the 

con so 1 e , 

u jJpdate 3,1,2,1 Uq sets Q-register q to a very large 

positive number. 
nUq sets Q-register q to n. 
m^nUq sets Q-register q to n and returns m 
as its value. This may be used inside 
a macro to get the numeric arguments 
to the macro. 



vw Ji/ieW 3.1.10 VVJ When this command is executed, one 

character is read from the console. 
The ASCII code for the character read 
is the value of the VW command. 



: vw 



3.1.10 



w 



Wipe out 3.1.15 



:VWq 



W 



Reads in an entire line from the 
console and puts it into Q-register q. 
The new! ine is the last character in 
the register. 



This command 
for throwing 
arguments. 



does nothing. It Is used 
away unwanted numeric 



of the current 



X e)(tract from buffer 3.1.3.1 Xq loads the rest 

line into Q-register < 
+nXq loads Q-register q 
from the current 
beginning of the next 
(0 or-n)Xq loads Q-register q 
from the beginning 
line to the current pointer. 
m^nXq load Q-register q with everything from 
the (m+1) character to the nth 
character . 



wi th eve ry th i ng 
pointer to the 
nth 1 i ne . 
w i th everyth i ng 
of the last nth 



:x 3.1.8.3 :Xq loads Q-register q with the next 

string argument to the macro we are 
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executing in. 

z Last Letter l,kB 1 This symbol's value is the total 

number of characters in the buffer. ZJ 
will move the pointer to the right of 
the last character in the buffer. 



% Increment 3.1.2.3 %q 



3.1.15 



If Q-register q contains a numeric 
value/ this command increments the 
1. The value of the 
the new value of the 



register by 
command is 
Q-regi ster . 



Throws away 
noth Ing. 



newl ine 



3.1.15 newl ine Throws away 

nothi ng. 



its arguments and does 
its arguments and does 



? Whats happening! 3.1.13 ? Turns tracing on. 
?? 3.1.13 ?? Turns tracjng off. 



<^ Number-character 3.1,1't <^ the value of this command is the 

decimal number immediately to the 

right of the pointer. It moves the 
pointer to just after the number. 

n(J: inserts the decimal representation of 
n to the left of the pointer. 

m,n<; inserts the decimal representation of 

m to the left of the pointer. The 
representation is padded on the left 
to be at least n characters wide. 

C Push 3.1.5.1 Cq Pushes the contents of Q-register q 

onto the pushdown list. 

1 Pop 3.1.5.2 Jq Pops the top element off the pushdown 

list and into Q-register q, 

< Begin a loop 3.1.6.1 < This marks the place in the command 

string that will be transferred to by 
the > command. This loop can only be 
exited by the ; command. 
+n< This loop will only execute n times. 
It may be exited by the ; command. 



> End a loop 3.1.6.1 > Transfer control to just after the 

last < command executed and decrement 
the loop count. If we have looped 
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enough times, this command does 
nothing. Nested loops are allowed. 

; Terminate if positive 3.1.6,2 ; If the last :S command was 

unsuccessful, transfer to just after 
the next > and exit the present loop, 
otherwise do nothing, 
n; If n is positive, transfer control to 
just after the next > command and exit 
the present loop, otherwise do 
noth i ng, 

"C If Symbol Constituent 3.1.9.2 n"C if n is the ASCII code for 

either a letter, a digit, "_"/ or 

"$", do nothing, otherwise transfer to 
just after the next *. 



i 
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"e If £qual 31 7.9.1 m,n"E If m=n then do nothing otherv/ise go to 

just after the next '. 
n"E if n=0 



"g If Greater 3.1.9.1 m,n"G if m>n. 

n"G if n>0. 

"1 If Less than 3.1.9.1 m,n"L if m<n. 

n"L If n<0. 

"n If Hot equal 3.1.9.1 m,n"N if m^=n. 

n"N if n''=0. 



Matches " 3.1.9.3 * marks the location a " command may 

transfer to. If executed as a command, 
it does nothing. 

3,1.9.3 :* marks the location a " command may 
transfer to. If executed as a command, 
it transfers to just after the next 
If statements may be nested, but " 
characters in the command string are 
only matched with one ' character, 
(See section 3.1.9) 



0 gQXo 3.1.7.1 o/label/ transfers control to just after llabel! 

1 Label 3.1.7.1 llabel! This entire construct is ignored if it 

is executed. 



Pointer l.kB . The value of this command is the value 

of the current pointer. 



teco 
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= Equals 2.1.9 = types out a newline. 

n= types out n on the console followed by 
a newl ine. 

m/n= types out m followed by a space^ 
followed by n^ followed by a newline. 

Note: For descriptions of operators In numeric 
expressions see section l.^fB 



(END) 



MULTICS PROGRAMMERS' MANUAL 




Command 

Author-Maintained Library 
J. M. Broughton 
Room 39-200, Ext. 3-7788 

2/25/74 

Name ; xpl 



The xpl command invokes the XPL compiler to translate an ASCII 
source segment into a Multics object segment. The segment will be 
placed in the user's current working directory, as will any listing 
segments produced. In general, this command behaves like standard 
system translators. 



Usage : 

xpl pathname -optionl- . . . -optionn- 

1) pathname is the relative pathname of the segment to be 

compiled. A suffix of ".xpl'' will be assiamed 
for the source segment if it does not appear. 



2) optioni 



may be selected from the following list of op- 
tions : 



-source, -sc 



-symbols , -sb 



produces a line-numbered printable ASCII 
listing of the program. The default is 
no listing. 

gives a listing of the source as above, 
and all the names declared in the program 
with their attributes. The default is no 
symbols . 



-map provides a listing of the source and sym- 

bols followed by a map of the object code 
generated. The default is no map. 

-list, -Is yields all of the above information, plus 

- an assembly-like listing of the compiled 

code. The default is no list. 

-execute, -ex allows the program to be executed despite 

severe errors detected during compilation. 
The default is to suppress execution. 



-libraryl, -libl causes the program to be compiled using a 

null string compaction routine. This is 
the default. 



xpl 
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-library2 , 



-lib2 



causes the program to be compiled using a 
real string compaction routine. This mode 
should be used by programs doing a large 
amount of string manipulation. 



~ times 



prints on the stream user__output information 
regarding the time used by various phases of 
the compiler. 



The XPL Language 

The XPL language was developed at Stanford University as part of 
a translator writing system. It is a simple dialect of PL/1 support- 
ing only automatic variables; all data types, except floating, are 
supported. Strings are implicitly varying, and arithmetic elements 
are of fixed scale and precision. It has certain features not found 
in PL/1, for instance, a limited macro facility, and built-in func- 
tions for performing shifts on full words. The best reference for 
the XPL language is found in A Compiler Generator by McKeeman, Hor- 
ning, and VJortman (Prentice-Hall, 1970) , Chapter 6. 

Notes on the Multics Imp lementa tion 

References to the functions input (i.) and output (_i) are used to 
do I/O. These functions cause data to be read or written on the 
streams xpl input i and xpl output i. The strecims for i = 0 are 
special-cased and the input comes from the stream user_input and out- 
put is directed to the stream user_output. The stream xpl_output_l 
is by default attached to error^output . To use any other stream, 
it must first be attached to a device by an appropriate iocall. 

References to the function file(i) may be used to move large 
blocks (one record, 10 24 words) of data to and from files. The files 
written or read are xpl_^file_i. By default, these files will be cre- 
ated in the process directory; to use a permanent file, one should 
put a link in his process directory to the desired file. 

All XPL programs on Multics are subject to certain restrictions: 
they cannot be bound, and they cannot be called recursively. In the 
former case, the binder will refuse to bind them, and though the lat- 
ter is possible, unpredictable results will occur. 

Certain built-in functions do not appear in this implementation: 
addr, clock_trap, interrupt_^trap , monitor^link, trace, and untrace. 
The built-in functions, arg__count, and argument (i^) have been added 
however. They give the number of arguments and the _ith argument re- 
spectively. The functions corebyte and coreword have slightly dif- 
ferent meanings. Corebyte is over lay ed, not on core, but on the 
string data area; coreword is overlayed on the arithmetic data area. 
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Author-Maintained Library 
Tom Van Vleck 
Room 39-513, Ext. 1749 
2/25/74 



Name : ask 



The ask_ module provides the programmer with a flexible ter- 
minal-input facility for whole lines, strings delimited by blanks, 
or fixed-point and floating-point numbers. Special attention is 
given to prompting the terminal user. 



Entry : $ask_ 



This entry returns the next string of characters delimited by 
blanks or tabs from the line typed by the user. If the line 
buffer is empty, "ask_" formats and types out a prompting mes- 
sage and reads a line from "user_^input" . 

Usage ; 

call ask_(ctl,ans ,ioa_args . . . ) ; 
ctl char(*) (input) 



1) 

2) 
3) 



ans char(*) (output) 
ioa_args (input) 



This is a control string in 
the same format as that used 
by " ioa_" . 

The return value. 

Any number of arguments to 
be converted according to 
"ctl". 



Entry ; $ask_clr 

This entry clears the internal line buffer. Because the buff- 
er is internal static, one program's input may accidentally be 
passed to another unless the second begins with a call to this 
entry. "ask_$ask__clr_" also can be called if a value typed by 
the user is incorrect and if the program wishes to ask for the 
line to be retyped. 



Usage ; 

call ask $ask clr; 
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Entry : $ask__int 

This entry works the same as "ask_$ask_" except that the next 
item on the line must be a number. An integer value is returned. 
Numbers may be fixed-point or floating-point, positive or nega- 
tive. A leading dollar sign or a comma will be ignored. If the 
value typed is not a number, the program will type 

"string" non-numeric. Please retype: 

and wait for the user to retype the line. 

Usage ; 

call ask_$ask__int(ctl,int ,ioa__args) ; 

1) ctl char(*) (input) As above. 

2) int fixed bin (output) The return value. 

3) ioa^args (input) As above. 

Entry ; $ask_flo 

This works like "$ask__int" except that it returns a floating 
value. 

Usage : 

call ask_$ask_flo(ctl,f lo,ioa_args) ; 

1) ctl char(*) (input) As above. 

2) flo float bin (output) The return value. 

3) ioa args (input) As above. 
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Entry : $ask_line 

This entry returns the remainder of the user-typed line. Lead- 
ing blanks are removed. If there is nothing left on the line, the 
program will prompt and read a new line. 

Usage ; 

call ask__$ask__line ( ctl , line , ioa__args ) ; 

1) ctl char(*) (input) As above. 

2) line char(*) (output) The return value. 

3) ioa__args (input) As above. 

Entry ; $ask__c 

This entry tests if there is anything left on the line. If so, 

it returns the next symbol, as in "ask_$ask__" / and sets a flag non 

zero. Otherwise, it sets the flag to zero and returns. 

Usage; 

call ask_$ask_c(ans ,f lag) ; 

1) ans char(*) (output) The symbol, if any. 

2) flag fixed bin (output) =1 if symbol returned. 

=0 if none there. 

Entry ; $ask_cint 

Conditional entry for integers. If an integer is available on 
the line, it will be returned and "flag" set to 1. If the line 
is empty, "flag" will be set to 0. If there is a symbol on the 
line, but it is not a number, it will be left on the line and 
"flag" will be set to -1. 

Usage ; 

call ask_$ask_cint(int,f lag) ; 
1) int fixed bin (output) Return value. 



2) flag fixed bin (output) 



=1 if "int" returned. 
=0 if line empty. 
=-1 if no number. 
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Entry ; $ask_cflo 

This entry works like "$ask_cint" but returns a floating value 
if one is available. 



Usage; 

call ask__$ask_cflo(f lo,f lag) ; 

1) flo float bin (output) 

2) flag fixed bin (output) 



Return . 

=0 if line empty. 

=1 if value returned. 

=-1 if not a number. 



Entry ; $ask_cline 

Conditional ask for rest of line 



Usage : 

call ask_$ask_cline( line, flag) ; 

1) line char(*) (output) 

2) flag fixed bin (output) 



Return value. 

=1 if line returned. 
=0 if line empty. 



Entry : $ask_n 

This entry "peeks" at the line and returns the next symbol 
without changing the line pointer. A call to "$ask_" later will 
return the same value. 



Usage; 

call ask__$ask__n(ans ,f lag) ; 

1) ans char(*) (output) 

2) flag fixed bin (output) 



Return symbol. 

=0 if line empty. 

=1 if symbol returned. 



1 
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Entry : $ask__nint 

Peek entry for integers. The second argument will be returned 
as -1 if there is a symbol on the line but it is not a number, as 
1 if successful, and as 0 if the line is empty. 

Usage; 

call ask_$ask_nint (int,f lag) ; 
Arguments as above. 

Entry : $ask__nflo 

Peek entry for floating. 



Usage : 

call ask__$ask__nf lo{flo, f lag) ; 

Entry ; $ask_nline 

Peek entry for rest of line. 

Usage; 

call ask_$ask_nline( line, flag) ; 

Entry ; $ask_setline 

This entry sets the internal static buffer in "ask_" to the 
given input line in order that the line may be scanned. 

Usage ; 

call ask__$ask_setline(line) ; 

del line char(*) 

Trailing blanks will be removed from line , A carriage return 
is optional at the end of line . 



ask 
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Entry : $ask_prompt 

This entry scraps the current contents of the internal line 
buffer and prompts for a new line. The line is read in, and the 
entry returns . 



Usage ; 



call ask__$ask_prompt (ctl , ioa__args . . . ) 



1) ctl char(*) (input) 



A control string similar 
to that typed by "ioa_". 



2) ioa args (input) 



Any number of arguments 
to be converted according 



to "ctl". 
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Subroutine Call 
Author-Maintained Library 
Joseph W. Dehn III 
Room 39-200, Ext. 3-7768 

3/12/75 



Name: attach__fortran__f ile_ 

This subroutine allows a program written in FORTRAN to 
specify the attachment for an I/O "file number" or "unit number". 

Usage : call attach_fortran_file_(ifile,astring,ierr) 

1) ifile is a FORTRAN file reference number, which must be 

between 1 and 99. 

2) astring is a character constant or variable which specifies 

the attachment. See Chapter 14 of the FORTRAN manual 
for the format of attachment specifications. 

3) ierr is a standard Multics error code. If the attachment 

was successful, ierr will be zero. 

call attach_f ortran_ssf ile_( ifile , path , ierr) 

2) path is a character constant or variable which specifies 

the pathname of a storage system file (segment or 
MSf ) . 

Notes : 

1) The second entry is for convenience only. The following two 
statements have the same effect: 

call attach_fortran__ssfile__(n , "a>b" , ierr) 
call attach_fortran__file_(n,"vfile_ a>b",ierr) 

2) when the program is done with the file, it should be closed 
using the "endfile" statement. The endfile statement will not, 
however, detach the file if it was attached using these 
subroutines or witn the io__call command. 

3) If the file specified by "ifile" is already attached, it will 
be closed and detached automatically when attach_f ortran_f ile_ is 
called. 



attach fortran file 
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Examples ; 



call attach_fortran_f ile_( 1 , "syn__ user_output" ,ierr) 

call attach_fortran__ssfile_( 6 , "output__seg" ,ierr) 

character*32 pathname 
read (5,10) pathname 
10 format (a32) 

call attach_fortran_ssfile_(kunit , pathname jierr) 
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Subroutine 
Author-Maintained Library 
Joseph W. Dehn III 
Room 39-200, Ext. 3-7788 

10/21/74 



Name ; basic__plot__ 

This subroutine is an interface which allows programs written 
in the BASIC language to use the "plot__" facility of the Multics 
Graphic System. For details of the operation of plot__, please 
see the MPM documentation. 

Usage: 



Initialization 



call "basic_plot_$init" :x$ ,y$/l,b,g,s 

x$ label for the X axis 

y$ label for the Y axis 

1 =1 for linear-linear 

=2 for log- linear 

=3 for linear- log 

=4 for log- log 
b logarithm base for 1>1 

g =0 for tic marks and values 

=1 for dotted grid and values 

=2 for solid grid and values 

=3 for no grid or values 
s =0 for normal scaling 

=1 for equal scaling 

Setting Scales 

call " has ic_plot_$ scale" :x1 ,x2 ,y1 ,y2 

x1 minimum X 

x2 maximum X 

y1 minimum Y 

y2 maximum Y 



Plotting 

call "basic__plotJ' :x() ,y() rn,v,s$ 

x() array of X values 

y ( ) array of Y values 

n number of elements in x() and y() 

V =1 for plotting with vectors 

=2 for plotting with vectors and symbol 
=3 for plotting with symbol only 

s$ the symbol for v>1 



basic plot 
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Notes : 

1) If the entry "basic_plot_$scale" is not called, automatic 
scaling will be performed. 

2) BASIC programs use zero-origined arrays. Therefore, to 
pass N points to basic_plot_^/ the values should be stored in array 
elements zero through N-1. "* 
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Subroutine 
Author-Maintained Library 
Joseph W. Dehn III 
Room 39-200, Ext. 3-7788 

7/27/74 



Name: 



check basic file 



This subroutine, intended primarily for use by BASIC programs, 
may be used to get information on a given file specification. 
By calling this routine before using the string in a "file" state- 
ment, the program can catch certain errors that otherwise would 
teminate the program. 



Usage ; 

call " check Joas i c_fi le_" : a$,c 

where a$ is the file specification, and c is an integer as follows: 

1 specification was null or blank 

2 specification was "*" 

3 pathname: bad syntax 

4 pathname: does not exist 

5 pathname: may exist, but no access 

6 pathname: exists but is zero length 

7 pathname: exists (segment) 

8 pathname: exists (msf) 

9 pathname: exists (directory) 

10 pathname: is the ROOT 

11 ioswitch: exists 

12 ioswitch: does not exist 

13 ioswitch: exists and attachment specified 

14 ioswitch: does not exist, but attachment specified 

15 ioswitch: bad syntax 

16 undefined error 

Note : 



The interpretation of the code "c" is left to the calling 
program. Values of (1,3,5,9,10,12,15,16) almost certainly indicate 
an error. Other codes may indicate an error or not, depending on 
how the file is to be used. For example, c=4 means segment does 
not exist, which would be an error if the program were going to 
read from the file, but not necessarily an error if the program 
were to write to it. 



Example : 

1 print "Name of file"; 

2 input a$ 

3 call "check__basic__f ile_" : a$,c 

4 on c goto 5,5,5,5,5,5,7,7,5,5,7,5,7,7,5,5 

5 print "Bad file name" 

6 go to 2 

7 file #1: a$ 
(rest of program) 
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Subroutine Call 
Author-Maintained Library 
Gary M. Palter 
Room 39-200, Ext. 3-7788 

2/25/74 



Name ; check jiisf_ 

This subroutine will determine if a specified directory is a 
multi-segment file. The definition of a multi-segment file used by 
this subroutine is given below. 



Usage ; 
del 

call 



checkjmsf_ entry (char(*) , char(*) , area(*) aligned, fixed 
bin(35)); 

check_jiisf_ (directory, entry, user^area, status__code) ; 



1) directory 



is the directory portion of the name of the 
branch to be tested. (Input) 



2) entry 

3) user__area 

4) status code 



is the entry portion of the above naime. (Input) 

is an area to be used for allocations. (Input) 

is a returned status code. (Output) 

The possible values of status_code are: 

0 The branch is a multi-segment file. 

error_table__$bad__ms _f i le 

The branch is a directory, but is not a multi- 
segment file. 

error_table_$nondirseg 

The branch is not a directory. 

Any error code which may be returned by hGS_$star_list_ and 
hcs_$status_long . 

Notes ; 

A directory is considered to be a multi-segment file by this sub- 
routine only if it satisfies all of the following conditions : 
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1) The directory has a non-zero bit count. 

2) The directory does not contain any links or directories. 

3) The number of entries in the directory is equal to its bit count, 
and each entry has exactly one name which is the character string 
representation of a number satisfying the condition 
0<number<bit count-1. 
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Subroutine 
Author-Maintained Library 
Tom Van Vleck 
Room 39-513, Ext. 1749 

9/8/70 

The procedure cv_ performs several useful number conversion 
calculations . 

Entry : $hrmin 

The entry point hrmin accepts a time in seconds and converts 
it to a time in hours and minutes, suitable for printing. The 
converted time is rounded u£ to the next minute, so that any 
nonzero input will produce a nonzero time. 

Usage : 

call cv_$ hrmin <ss,hr, rain) ; 

1) ss fixed (input) Input time in seconds. 

2) hr fixed (output) Hours. 

3) min char(*) (output) Minutes, 4 chars. 

Entry ; $absdat 

The entry point absdat returns the number of days since 
January 1, 1901, given the month, day and year as input. 

Usage : 

call cv_$absdat (mo,da,yr,abs) ; 

1) mo fixed (input) Month 

2) da fixed (input) Day 

3) yr fixed (input) Year 

4) abs fixed (output) Absolute date 



cv 

~ J 
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Entry ; $shift 

The routine shift computes the current accounting shift 
numbers • 

Usage ; 

call cv $shift (mo,da,yr ,hr ,sh) ; 



1) mo 


fixed (input) 


Month 


2) da 


fixed (input) 


Day 


3) yr 


fixed (input) 


Year 


4) hr 


fixed (input) 


Hour 


5) sh 


fixed (output) 


Shift number 


Entry: 


$mwvf 





The routine mwvf converts a floating dollar cimount to ASCII 
characters . 

Usage : 

V = cv__$mwvf (f lo) ; 

1) flo float (input) 

2) V char(15) (output) 

The converted value will have a floating dollar sign and 
commas every three digits. Blanks will be returned if the 
number is all zero. The value is right-justif ied. Fifteen 
characters will be returned. 

Examgle: 

Input Returned 

1234.567e0 $1,234.57 

O.OOleO $.00 
O.OeO 

-5.7e0 $-5.70 

1.234el0 $**^***^***.** 
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The entry cdate converts a character-string date into a double- 
precision integer in system calendar clock format, i.e., in micro- 
seconds since OOOOGMT, January 1, 1901. The date may be expressed 
flexibly. An invalid date will convert to 0. A date of "*" 
returns the current time. 



Usage ; 

call cv__$ cdate (date, time) ; 

1) date char(*) (input) Date 

2) time fixed bin (71) (output) Time 
Example : 

The date June 1, 1970, may be expressed as : 



060170 

6/1/70 

0601 

6/1 

06/1 

6/01 

061/70 

6/0170 
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detach fortran file 



Subroutine Call 
Author-Maintained Library- 
Joseph W. Dehn III 
Room 39-200, Ext. 3-7788 

3/12/75 



Name: detach fortran file 



This subroutine allows a program written in FORTRAN to 
detach a file that was attached using the "io_call" command or 
using the "attach_fortran_f ile_" subroutine. 

Usage ; call detach_fortran_f ile__( if ile , ierr ) 

1) ifile is a FORTRAN "file number" or "unit number" in the 

range 1 to 99. 

2) ierr is a standard Multics error code. If the detach was 

successful, ierr will be set to zero. 



Example : 



call detach__fortran_f ile_( 1 ,ierrcode) 
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fillin dprint str 



Subroutine 
Author-Maintained Library 
Edward McCabe 
575 Technology Square 
Fifth Floor, Ext. 3-1533 

7/9/74 

Name ; f illinjdprint_str__ 

Usage ; declare fillinjdprint_str__ entry (char(*) varying, 

pointer, fixed binary (35)); 



call fillinjdprint__str_(optstring, dpap, ercd) ; 



Where: 



optstring is the string used to fill in the dprint_arg 
structure based on dpap. 

dpap is the pointer to the dprint^arg structure. 

Only structures of version = 1 are accepted 
by this s\ibroutine. 

ercd is an error code returned by this subroutine 

which can assume the following values : 

0 no errors were encountered. 

1 the structure was not version = 1. 

2 an error was encountered in the parsing 
of the options. 

This routine assumes that the caller will choose and control 
the defaults of the dprint_arg structure as required by the 
dprint__ subroutine. As a result, only those values which are 
explicitly specified in optstring will be affected by this sub- 
routine . 

Structures which are not understood, i.e., version =1 will 
be rejected. Errors encountered in the parsing of optstring will 
cause a message to be printed (via com_^err_) , but any of the rest 
of the structure which is appropriate will be filled in. 

Finally, if 'dpunch' , 'dprint', or 'dp' appear at the beginning 
of the string, they will be ignored (since it may be convienent to 
pass a string containing them, rather than parsing them out) . 

This subroutine accepts the following options : 

-print specifies that both dprint__arg . pt_pch and 

dprint_arg . outputjnodule are to be set to 
1 (for printed output) . 



-punch 



specifies that both dprint__arg.pt^ch and 
dprint_arg.output_module are to be set to 
2 (for punched output) . Note that the 
default is 7punch. 



f i 1 lin jdpr in t_s tr 
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The use of any of the three following options results in 
setting dprint_arg.pt_pch to 2 (for punched output) . 



■mcc 



-raw 



specifies that dprint_arg.output__module 
is to be set to 3 for MCC punch. 

specifies that dprint_arg.output_module 
is to be set to 4 for raw punch. 



-7punch, -7p 
-cp n, -copy n 
-dl, -delete 
-header header, -he header 



specifies that dprint^arg.outputjmodule 
is to be set to 2 for 7punch. 

specifies that dpr in t__arg. copies is to 
be set to n. 

specifies that dprint_arg. delete is to 
be set to 1. 



specifies that dpr int^arg. header is to 
be set to " for " header . Note that 
this results in the correct header for 
the output. 

-ds dest, -destination dest 

specifies that dprint__arg.dest is to be 
set to dest . 

~<I B.' ~<3ueue n specifies that dpr int__arg. queue is to be 

set to n. 

cig^ss y -device^class class 

specifies that dpr int^arg. class is to be 
set to class. 



Any option can be overridden by a succeeding option except 
the -delete, -dl option. 
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f ixed__to__english_ 



Subroutine 
Author-Maintained Library 
Student Information Processing Board 
Room 39-200, Ext. 3-7788 

9/6/74 



Name ; f ixed_to_english__ 



This subroutine returns the spelled-out English representation 
of a fixed binary number. 

Entry ; f ixed_to_english_ 

This entry converts a fixed binary value and uses the prefix 
"minus" to indicate a negative niamber. 

declare f ixed_to_english_ entry (fixed bin (35)) returns (char (*)) ; 

ou tpu t_s tr i ng= f ixed__to__engl i sh_ ( numbe r ) ; 

Entry ; f ixed__to_english_$ownjotiinus 

This entry converts a fixed binary value and uses a user- 
specified prefix to indicate a negative number. 

declare f ixed_to__english_$ownjninus entry (fixed bin (3 5), char(*)) 
returns (chau: (*) ) ; 

output_string=f ixed_to_english__$ownjninus (number ,minus_word) ; 
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get_cal ler^tr_ 



Subroutine Call 
Author-Maintained Library 
Student Information Processing Board 
Room 39-200, Ext. 3-7788 

4/13/73 



Name ; get_caller_ptr 



This subroutine is an ALM utility module which returns poin- 
ters to the text sections o£ various ancestors of the calling pro- 
gram. 

Usage ; 

declare get_caller_ptr_ external entry returns (pointer); 

caller_j)tr = get_caller_ptr_ () ; 

1) callerjptr is a pointer to the text section of the direct an- 
cestor of the procedure calling get_caller_ptr_. 
(Output) 

Entry ; get_caller_j)tr_$myjptr 

This entry returns to the calling program a pointer to its 
own text section. 

Usage ; 

declare get_caller ptr_$my_ptr external entry returns 
(pointer); " 

myjptr = get_caller_ptr_$my_ptr () ; 

1) my_j>tr is a pointer to the text section of the procedure 

calling get_caller^ointer_$myjptr. (Output) 

Entry ; get_caller_ptr_$backstack 

This entry returns to the calling program a pointer to the 
text section of its nth ancestor, where the O^th ancestor is de- 
fined as the progreun calling get_caller^tr_$backstack. 



Usage ; 



declare get_caller_j>tr_$backstack external entry (fixed 
binary) returns (pointer) ; 

any_ptr = get_caller_ptr_$backstack (n) ; 
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1) n is the ancestor for which a pointer to the text 

section is desired. If n is zero, the pointer re- 
turned is the same as would be returned by 
get_caller_j>tr_$my_ptr . (Input) 

2) any_j)tr is the pointer to the text section of the nth 

ancestor of the program calling 
get__caller_ptr_$backstack. (Output) 
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Subroutine 
Author-Maintained Library 
Student Information Processing Board 
Room 39-200, Ext. 3-7788 

9/6/74 



Name ; get_line_length_ 



This subroutine may be used to find the line^length of a 
specified io-switch. It should normally only be used on an io- 
switch that is associated with a terminal. 

Usage ; 

declare get_line_length_ entry (char (*) ) returns (fixed bin) ; 
line_len=get_line__length__( switch_name) ; 

1) switch_name is the name of the io-switch. 

2) line_len is the number of characters per line; if this 

value cannot be determined, it will be zero. 
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get seg ptr 



Subroutine 
Author-Maintained Library 
Richard H. Guiapertz 
Senior House, Ext. 289 3 

11/5/73 

Names ; get__seg__ptr_ 

ge t__s eg jp tr_arg_ 
ge t_s eg_j> tr_f u 1 l__path_ 
ge t_s eg jp tr _s e ar ch_ 
re leas e_s eg_j) tr_ 

This procedure consists of entries to initiate and terminate 
data segments. It also is capable of creating, truncating and 
setting the bit count on segments. It is more useful than the 
current Multics file primitives because it expands pathnames, 
creates segments and initiates all in one call by the user. 
Similarly, it sets the bit count, truncates the segment and temi- 
nates all in one call. 



Entry ; get__seg_ptr_ 

This entry initiates a segment given a relative pathname and 
checks access to the segment. If the segment does not exist, it 
will be created if the user so requests. 

Usage ; declare get_seg__ptr__ external entry 

(char(*) , bit (6) aligned, fixed bin (24) , ptr, 
fixed bin ( 35) ) ; 



call get__seg_ptr_ (pathname, wanted_access , bit_count, 

return_ptr, return_code) ; 

VJhere ; 

pathname is a relative pathname to the segment. (Input) 

wanted_access is the requested access to the segment. The 

first five bits are considered to indicate the 
standard Multics access control bits . They 
are "t" (trap, not currently implemented) , "r" 
(read) , "e" (execute) , "w" (write) and "a" 
(append), respectively. If the segment exists, 
then an error code (error_table_$moderr) will 
be returned if the user does not have at least 
the access requested. Note, however, that 
return_ptr will contain a valid pointer even 
if this error occurs . The sixth bit is inter- 
preted as a "c" (create) bit — if the segment 
does not exist, it wi?l be created if this bit 
is on. If a segment is created, it is given 
the access bits specified by the t, r, e, w, and 
a bits. (Input) 
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is the bit count of the segment. (Output) 

is a pointer to the segment. If the segment 
is not initiated, this pointer will be returned 
containing the null pointer. (Output) 

is the standard Multics error code. The only 
condition under which this code will be non- 
zero when the return^ptr is non-null is if 
the error is error_table_$moderr . (Output) 

Entry : release__seg_ptr_ 

This entry terminates a segment initiated by one of the entries 
to get_seg_ptr_. If a bit count is specified, the bit count of 
the segment is set and the segment is truncated to the correspond- 
ing length. 

Usage : declare releasees eg_ptr_ external entry (ptr, fixed bin (24) , 
fixed bin (35) ) ; 

call release_seg_ptr _ (seg^tr, bit_count, return_code) ; 

Where : 

seg^tr is a pointer to the segment to be termi- 

nated. (Input) 

bit_count is the bit count to be set on the segment. 

If this argument is negative, it is assumed 
that the bit count should remain the same 
and no truncation should take place. (Input) 

return_code is a standard Multics error code. (Output) 

Entry : get_seg_ptr ^arg_ 

This entry is identical to get_segjptr_ except that it obtains 
the pathname of the segment to be initiated from the caller's 
argument list. It saves a call to cu_$arg_ptr_. 

Usage : del get_seg_ptr__arg_ external entry (fixed bin, bit (6) 
aligned, fixed bin(24) , ptr, fixed bin(35)); 

call get_seg_ptr_arg__(arg__number , wanted^access , bit__count, 

return^tr, return_code_; 

VJhere : 

arg number is the number of the caller's argument to be 

used. (Input) 

All other arguments are identical to get__seg j)tr . 
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bit ^count 
re turnip tr 

return code 



get_seg__ptr 
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E ntry ; get_seg_j)tr_full_j)ath_ 

This entry is identical to get_seg_ptr_ except that the 
pathname is specified as an aibsolute pathname in directory/entry 
form. 

Usage ; declare get__seg_j>tr__full_path_ external entry 

(char(*) , char(*) , bit (6) aligned, fixed bin (24) , ptr, 
fixed bin (35) ) ; 

call get_segjptr__full_path_(dir_name, entry _name , 

wanted_^access , bit_count, 
return3>tr, return]^code_; 

Where : 

dir_name is the absolute pathname of the directory 

of the segment. (Input) 

entry_name is the entry name of the segment. (Input) 

All other arguments are identical to get_seg_ptr_. 

Entry ; get_seg_ptr_search_ 

This entry is identical to get_seg^tr_ except that just an 
entry name is specified. The directory is determined by Multics 
search rules. If the segment is not found and if the "c" (create) 
bit is on, then the segment is created in the process directory. 
Note, however, that if the entry name is not known as a reference 
name before a call to get__seg_ptr_search_, this entry will not 
cause it to be made known. This procedure initiates the segment 
with a null reference name. This has the net effect that full 
search rules will be follov;ed each time this routine is called. 

Usage ; declare get__seg_ptr_search_ external entry 

(char(*) , bit(6) aligned, fixed bin(24) , ptr, fixed bin(35)); 

call get_segjptr_search_ ( entry _name , wanted_access , bit_count 

return_j)tr, return_code) ; 

Where : 

entry_name is the entry name of the segment to be 

found. (Input) 

All other arguments are identical to get_seg_ptr_. 
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Examples ; 

^* 'ES. ^^^^ £ segment 

declare file aligned char (262144) based (file_ptr) , 
r_access bit (6) aligned int static init ("010000" b) ; 

call get_seg_ptr_ (file_name, r^access, count, file_ptr, 

error_code) ; 

if error_code~'= 0 then go to error; 

count = divide (count, 9, 17, 0); 

string_variable = siabstr (file, 1, count) ; 

call release_seg_ptr_ (file_j)tr, -1, error__code) ; 

if error__code"'= 0 then go to error; 

declare file aligned char(262144) based (file_ptr) , 
rwac_acess bit(6) aligned int static init ("010111" b) ; 

call get__seg_ptr_ (file__narae, rwac_access, count, file_ptr, 

error _code) ; 

if file_ptr = null then go to error; 

count = length (string^variable) ; 

substr (file, 1, count) = string_variable; 

call release_seg_ptr_ (file^tr, count*9, error^code) ; 

if error_code"'= 0 then go to error; 

3. To search for a segment 

Program "x," whenever entered, does a search for a segment 
called "init.x" which, if found, is used to initialize x. 
This could be done as follows : 

call get_seg_j)tr_search_( "init.x" , "010000" b, count, file^ptr, 

error code) ; 



get_seg_ptr_ 
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if file_j)tr"'= null then /*initiate only if found*/ 
init: do; 

count = divide (count, 9, 17, 0) ; 

/*do initialization*/ 

call release_seg_ptr_ (file_ptr, -1, error _Gode) 
if error_code~'= 0 then go to error; 
end init; 
/* rest of program*/ 
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Subroutine Call 
Author-Maintained Library 
Student Information Processing Board 
Room 39-200, Ext. 3-7788 

4/11/73 



Name ; get_mydir_ 



This subroutine allows a procedure to ascertain the directo- 
ry in which it resides. 

Usage : 

declare get_mydir_ external entry (char (*)); 

call getjnydir_ (dir^name) ; 

1) dir_name is the name of the directory in which the procedure 
calling get_mydir_ resides. (Output) 

Entry ; get_refdir_ 

This entry allows a procedure to ascertain the directory in 
which its caller resides. 

Usage ; 

declare get_refdir_ external entry (char (*)); 

call get_refdir_ (dir^name) ; 

1) dir_name is the name of the directory in which the caller of 
the procedure calling get_refdir_ resides. (Output) 
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SuDroutine Liorary 
Author-Maintained Library 
Overlap Prolect Staft 
N£i*i3-5a3, 253-2053 
11/19/74 



MamfiS IMSL Library 



The IMSL Library is a collection of approximately 300 
mathematical and statistical subroyt inest written in FORTRAN. 
These routines hawe been compiled on the MIT Multics machine as 
part of work on the Consistent System. They are being maae 
available to the community in subroutine form as well. 

The bulk of this description is intended to give the reac-er 
an idea ot the range of capabilities of the library. Documents 
describing it are on file in the IPC Reading Room (39-'+3i3)» and 
can be purchased from 

IMSL 

6200 Hillcroft, Suite 5ic 
HoustORf Texas 77036 

Anyone interestea shoula contact the Overlap Project Staff at the 
aoaress above (Nt^O is 575 Technology Square) tor more 
information* 

These subroutines are in "> I ibrar ies>imsl " which must be in the 
user's search path. To do this» enter the command "ssd 
> I i brar ies> iras I or "asr >l ibrar ies>ims 1". 



RESTRICTIONS and DISCLAIMER 

The library is proprietary. Its use is licensed to the 
Overlap Project ana to the MIT Multics. Attempting to carry 
the library to another machine is prohibited py the license 
agreement. The lease is on a year by year basiSt and the 
Overlap Project can make no guarantee to the community that 
it will renew the lease for any given period. Final ly^ 
while parts of the liorary have oeen testea in the Multics 
environment ana founc to be of very high quality we can make 
no guarantees about the correctness of the routines. IMSL 
does certify them ana is of consiaeraoJe help if a user of 
the library gets into substantive mathematical trouble with 
it; requests for such assistance should be directed to the 
Overlap Project as holaer of the leisse. A summary of 
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RioQl f icat ions we have maoe to the library* ana for which 
IHSL bears no responsibility* appears bestow. 



The library is arranged within subgroups* caHad "chapters'*. 
These chapters are titled as followst (1) 
Analysis of Experimental Design Data 

(includes analysis of variance and classification routines) 
Basic Statistics 

(incluaes elementary bayesian inference* data screening* and 

elementary classical inference! 
Categorized Data Analysis 

Differential Equations? Quadrature? Differentiation 
Eigenanal y s is 

Forcasting* Econometrics? Time Series 

Generation and Testing of Random Numbers? Goodness of Fit 
Interpolation? Approximation? Smoothing 
Linear Algebraic Equations 

Mathematical and Statistical Special Functions 

(induces probability cistrioution functions ana special 

functions of mathematical physics) 
Noi-Parame tr ic Statistics 

(includes analysis of variunce* binomial or multi-nomial 

bases* ko 1 mogorov-smirnov tests* randomization oases) 
Observation Structure 
Regression Analysis 
SampI ing 

Utility Functions 
( see No t e 1 ) 
Vector* Matrix Arithmetic 
Zeros ano Extrema? Linear Programming 



The following list is a summary* some Knowledge of the library 
may be requireo to understand it« 

1) Chapter U* which contains Utility Functions* has not been 
implemented. It contains a series of functions for 



(i) This material is taken* in large part from IHSL publication 
LIB-CiOO^ 
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input/output and the like* The maintainers are willing to 
supply the source to anyone seriously interested in oringing 
up this Chapter on Hultics. 

2J Routines that are indicated in the manual as aeing av/aifable 
in double or single precision have been proviJeu in single 
precision only. 

3) All calls to the IMSL error message printing routine* 
UERTSTt have been removed. The routines still r^iturn error 
codes* 

The names of all subroutines, functions, anj entries into 
them have been changed to insure that conflicts will not 
occur with the aynamic linking mechanism on Mul tics. The 
renaming rule is as followss 

a) Find the subprogram in the IMSL manual. At the heaa of 
the description is a listing of some comment cards, at 
the eno of which is an eight character "card label**. 
The first four characters of the "carJ label" is a 
four-Character "deck label". 

D) For the main entry point, take the deck label, change its 
characters to lower cast, and prefix them with "cs_i" 
to obtain the subroutine name. 

c) For any adcitional entry points, adu the digit "1" to 
the subroutine name for the first one, "2" for the 
second, etc. 



5) The i ibrary eaition implementea on Multics was originally 
designed for the Univac litiS. Due to aitferences in Fortran 
compilers anci machine structure, changes have been required 
to constants and the order of statements, and a special 
overflow proceoure written in PL/I has oeen provided* 
Unless problems arise with them, these modifications shoula 
be transparent to the user. A complete list of these 
modifications is available from the Overlap Prolect, and 
with the Reading Room copy of the IMSL manuals* 
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Subroutine 
Author-Maintained Library 
Edward J. McCabe 
575 Technology Square 
Fifth floor. Ext. 3-1533 

2/21/74 



Name ; linear_q_hash , Iqh 

li ne ar__q__^h ash_ , lqh__ 



The subroutine linear_q__hash is an implementation of the lin- 
ear quotient hashing algorithm described by Bell and Kaman in the 
November, 19 70, issue of the Communications of the Association 
for Computing Machinery (pp. 675-677) . 

Usage : 

call linear__q_hash (result, residue, table^size, word) ; 
Arguments : 

declare (result, residue, table__size) fixed binary ( 35 ,0) ; 
declare word char (32) varying; 

Where : 

result is in the range 0<=result<table__size. (output) 

residue is in the range l<=residue< (2**35) . (output) 

tablets ize is a prime integer. (input) 

word is the source word to be hashed . ( input) 

Entry point for retries ; 

call lqh$re try (result, residue, table__size) ; 

Although arguments are declared identically, their significance 
is different on retries . 

result is both input and output. On input, it is 

the most recently returned result from Iqh 
or lqh$retry. On output, it is a new value 
of result. 

residue is the value of residue last obtained from 

Iqh or lqh$retry. (input) 

table_size is the original prime that defines the 
range. (input) 



linear q hash 
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This subroutine, given a character string (word) and a prime number 
(table_size) , will produce a pseudo-random result in the range 
0<=result<table_size, plus a residue of unpredictable size (less 
than 2**35, however) . This result may be used to reference a 
location in a hash table. If this location is unsuitable, up to 
table_size - 1, retries may be made; complete coverage of the 
range is guaranteed. Retries must be attempted by returning the 
most recently obtained values for "result" and "residue," in 
order to ensure complete coverage of the range. The user must 
keep track of the number of retries attempted. 

Note that the key is constructed using only the information-carrying 
bits of the first five characters of the source word (padded on 
the right with blanks, if necessary) . On Multics, these are the 
right-most seven bits of each character. 

Note that linear_q__hash, Iqh, linear_q_hash_ and lqh_ are synony- 
mous for both entry points. 
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Subroutine 
Author-Maintained Library 
J. M. Broughton 
Room 39-200, Ext. 3-77 88 

9/30/73 



Name ; qd 

This procedure is used to determine if an instruction with a 
given opcode modifies the contents of the q-register. 

Usage ; 

declare qd entry (fixed bin{35)) returns (fixed bin(35)); 

modified = qd (opcode) ; 

1) modified is one if the instruction alters the q-register, 

zero otherwise. 



2) opcode 



is the opcode of the instruction in question. 
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reverse index 



Miscellaneous Call 
Author-Maintained Library 
John C. Klensin 
575 Technology Square 
Fifth floor, Ext. 6217 
1/18/71 



Name ; reverse index 



This function searches a character string from right to left 
for a particular character string. The location returned is in 
characters from the left. 



Entry ; reverse_index_^$reverse_index_ 

This entry returns the index position (from the left) of the 
first character string (from the right) equal to the specified 
string . 

del reverse_index_ ext entry (char (*), char (*) ) returns ( fixed bin) ; 
i = reverse__index_(stringl ,string2) ; 
Where: 



i is the index position from the left of the string. 

It will be 0 if the string specified in string2 is 
not in stringl. (output) 

stringl is the string to be scanned for string2. (input) 

string2 is the comparison string. (input) 

Entry ; reverse_index_$notequal 

This entry returns the index position (from the left) of the 
first character not equal to the specified character. (This is 
useful for finding the last nonblank character in a word.) 

del reverse_index_$notequal ext entry (char (*), char (1) ) returns (fixed bin); 

i = reverse_index_$notequal (stringl , char) ; 

Where : 

i is the index position from the left of the string. 

It will be 0 if the string is not found in stringl. 
(output) 

stringl is the string to be scanned for char. (input) 

char is the character to be searched for in stringl. (input) 

Note: reverse_index_ is similar to the PL/I "index" built-in 
function, except that it searches the string from the opposite direc- 
tion; the position in the string is expressed in the same fashion. 
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scan 



Subroutine 
Author-Maintained Library 
J. Klensin 
575 Technology Square 
Fifth Floor, Ext. 6217 
5/24/71 



Name : scan 



The procedure scan__ contains a number of functions that scan 
across a supplied character string looking for an occurrence of 
any single character from a second string. Functions are supplied 
that scan the string from left to right and from right to left, 
and that look for the first character equal to and the first 
character not equal to any of those in the second string. 



Entry : scan__$scan__ 

This entry is used to find the first character in one string 
that matches any character in a second string. It returns, as do 
all of the functions below, the index of the located character 
from the left of the first string. 



Usage : 

del scan_$scan_ ext entry (char (*) ,char (*) ) returns (fixed bin); 
i=scan_$scan_ (stringl, string2) ; 

stringl is the string to be scanned for the first occurrence of 
a character in the second string. 

string2 is the string containing characters to b.e located in the 
first string. 

i is the index (from the left) of the first character in 

stringl to match any character in string2. If no 
character in stringl matches any character in string2, 
"i" is set to zero. 



scan 



Page 2 
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Entry ; scan__$scan__notequal 

This entry is used to find the first character in one string 
that does not match any character in the second string. (Note: 
This entry point is equivalent to the VERIFY function existing in 
certain implementations of PL/I.) 



Usage ; 

del scan_$scan_notequal ext entry (char (*), char (*) ) returns (fixed bin) 
i=scan__$scan__notequal (stringl ,string2) ; 

stringl is the string to be scanned for the first occurrence 
of a character not in the second string. 

string2 is the string containing characters to be located in 
the first string. 

i is the left index of the first character in stringl that 

does not match any character in string2. 



Entry : scan_$ scan_r ev 

This entry is used in a fashion similar to scan_$scan__, 
except that it searches the string from the right. (Note: This 
is not the Scime as AML subroutine reverse index , ) 



Usage : 

del scan_$ scan_rev ext entry (char (*), char (*) ) returns (fixed bin); 
i=scan_$scan_rev (stringl , string2) ; 

stringl is the string to be scanned from the right for the first 
occurrence of a character in the second string. 

string 2 is the string containing characters to be located in the 
first string. 

i is the index (from the left) of the first character in 

stringl to match any character in string2. If no 
character in stringl matches any character in string2, 
"i" is set to zero. Note that "i" is still a left 
index . 
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Entry ; scan__$scan_notequal_rev 

This entry is used in a fashion similar to scan_$scan_not equal, 
except that it searches the string from the right. 



Usage ; 

del scan__$scan_notequal_rev ext entry (char (*), char (*) ) 
returns (fixed bin); 
i=scan_$scan_notequal_j:ev (stringl, string 2) ; 

stringl is the string to be scanned from the right for the 
first occurrence of a character not in the second 
string . 

string2 is the string containing characters to be located in 
the first string. 

is the left index of the first character in stringl 
that does not match any character in string2. 

scan__$ scan__ptr 
scan_$ scan__ptr__notequal 
scan_$ scan_j)tr__rev 
scan__$ scan__ptr__notequal_rev 

These entries correspond to the ones above, except that they 
accept a pointer and a length to designate the first string, rather 
than having the string passed directly. 



Usage ; 

The first of these is typical of the others. 

del scan__$scan_ptr (pointer , fixed bin,char(*) ) returns (fixed bin) 
i=scan__$scan__ptr (ptr_to_stringl,lengthjof__stringl,string2) ; 

i and string2 are the same as defined above. 

ptr__to__stringl is the pointer to the first string. 

length_of _stringl is the length of the first string. 



i 



Entry ; 



scan 
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Disclaimer ; 

No claim is made that these functions are fast or that they 
could not be done more efficiently with in-line code. The 
functions have proved convenient to get some types of code work- 
ing that could be optimized later or that did not require 
optimization . 

For the reason mentioned in the note above, the function 
scan_$scan_notequal may be withdrawn when the PL/I verify BIF 
becomes available. 
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tek 



I/O System Device Interface Module 
Author-Maintained Library 
Student Information Processing Board 
RoCHDti 39-200, Ext. 3-7788 

2/25/74 



Name : tek 



The tek_ DIM allows a user to perform graphic input and out- 
put on a Tektronix 4002, 4012, or 4013 type terminal. 

Usage : 

call ios_$attach (stream__name, "tek__", to_str earn, mode, 
status) ; 

1) stream__name is usually "graphic^output" or "graphic_input" . 

2) to_stream is usually "user__i/o", but may be any other stream. 

(Input) 

3) mode is ignored. 

4) status is a standard I/O system status code. (Output) 
Permitted I/O System Calls ; 

The following I/O system calls are implemented by this DIM: 



attach 

detach 

read 

write 

order 



Returned Status ; 

With the exception of the error returned upon attempted multiple 
attachment, this DIM will only reflect status codes from downstream. 



Order Request ; 

Only one order request is implemented by this DIM: 

screen_size causes the output and input to be scaled so that 
the maximum square physical screen size of the 
terminal (760 x 760) represents a virtual screen 
size of (N X N) , where N is a fixed binary number 
pointed to by the pointer argument to ios_$order. 
The default is standard for the Multics Virtual 
Terminal screen (1024 x 1024) . 



tek 
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Graphic Input Format : 

Any read call issued through tek_^ will activate the cross- 
hair cursors for graphic input. The""graphic input portion of the 
DIM simulates the operation of an ARDS mouse or joystick. To 
send any graphic input command, the user must type one character 
followed by optional text, followed by a newline character. The 
coordinates of the crosshair intersection are sent with the first 
character, and the character itself specifies the action to be 
taken. Because of the terminal architecture, the desired con- 
structs will be echoed on the screen after every request. Allow- 
able characters are: 

s (setposition) Causes a setposition to the current location 
to be sent. 

V (vector) Causes a vector to be drawn from the last coordin- 
ate point to the current location. 

i (shift, stands for "invisible vector") Causes a relative 
shift to be generated to the current position. 

p (point) Causes a shift to the current position, and dis- 
plays a visible point. 

t (text) (followed by text before the newline) Causes a text 
string to be generated at the current position. If the 
current position differs from the position at the last 
command, a shift is generated to the new position. 

e (escape) (followed by text before the newline) Signifies 
that the text string is to be treated as a normal, non- 
graphic ASCII string. If this does not occur as the first 
entity for any particular read call, it is ignored. This 
entity causes termination of the read call. 

q (quit) Sends a setposition at the current position, and 
terminates the read call. 

The input stream is in Multics Graphic Code format, and may be 

read and parsed by using the subroutine gf__^input_^ rather than having 

a program issue a read call directly. 
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tek dim 



I/O System Device Interface Module 
Author-Maintained Library- 
Student Information Processing Board 
Room 39-200, Ext. 3-7788 

2/25/74 



Name ; tek__dim_ 

This is the PL/I procedure which implements the functions of 
the tek_ outer module. It is documented under the writeup for 
tek • 
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Subroutine 
Author-Maintained Library 
J. M. B rough ton 
Room 39-200, Ext. 3-7788 

9/30/73 

Name ; xcom 

This is the compiler for the XPL language. 
Usage ; 

declare xcom entry options (varic±>le) ; 
call xcom (entry, toggles, time); 

1) entry is the character string forming the entry name 

for the segment. (Input) 

2) toggles contains compiler toggles to be set initially on. 

( Input) 

3) time is a character string containing a date/time 

string for the listing of the program. (Input) 

All the above variables should be declared character (*) . 
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xpl file 



Subroutine 
Author-Maintained Library 
J. M. Broughton 
Room 39-200, Ext. 3-7738 

9/30/73 



Name : xpl_file 



This routine is used to perform file I/O for XPL programs. It 
moves data in 10 24 word blocks. Files are kept in the process di- 
rectory, and have names of the form xpl file n. 



Usage 



declare xpl_file (fixed bin(32) , fixed bin(32) , bit (1) 
aligned, fixed bin(32)); 

call xpl_file (file, block, output, dummy) ; 



1) file 



2) 
3) 



block 



output 
4) dummy 



is the file number of the segment to be read or 
written. If it does not exist, it will be cre- 
ated. Only zero to nine is allowed. 

is the block number of the block to be read or 
written. It starts at zero. 

if "l"b, the file will be written, if "0"b, it 
will be read. 

is the first word of the block to be read from 
or written into. 



declare xpl f ile$truncate entry; 
call xpl file$ truncate; 



This truncates all files used by an xpl program and which are cur- 
rently active. 



MULTICS PROGRAMiMERS ' MANUAL 



Siibroutine 
Author-Maintained Library 
J, M. B rough ton 
Room 39-200, Ext. 3-7783 

9/30/73 

Name ; xpl_loader_ 

This routine is used to move the data portion of an xpl program 
into a scratch segment in the user's process directory. Scalar and 
arrary data are placed in the segment "xpl_arith_data_ ' ; string data 
are placed in "xpl_string_data_" . It is called with one argument: 
a pointer to a structure of pointers to the different areas that are 
to be filled in. 

Usage : 

declare xpl__loader__ entry (pointer) ; 
call xpl_loader_ <regptr) ; 
1) regptr is a pointer to the structure described above: 

declare 

1 registers aligned based (regptr) , 
2 data pointer, 
2 string pointer, 
2 array pointer, 
2 text pointer. 

The pointer text is an input parameter, and 
points to the base of the object segment. 

Note : 



xpl loader 



This routine is, and should only be, called by the prologue 
sequence of an xpl program. 
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xpl_operators__ 



Subroutine 
Author-Maintained Library 
J. M. Broughton 
Room 39-200, Ext. 3-7788 

2/25/74 



Name : xpl_pperators_ 



This routine is called by an xpl program in order to perform 
tasks that it cannot do for itself. 

Usage ; 

declare xpljoperators^ entry (pointer) ; 
call xpl operators^ (stack ^tr) ; 

1) stack_ptr is a pointer to the stack frame of the calling 

procedure • 

Notes : 



This procedure is, and should only be, called by code as gener- 
ated by the xpl compiler. 
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all 



Active Function 
Author-Maintained Library 
John C. K lens in 
575 Technology Square 
Fifth Floor, Ext. 6217 
12/7/71 



Name: all 



The active function all returns the contents of a designated 
segment with all of the new line characters changed to blanks. 
It is useful when a list of things must be done by several com- 
mands in succession or when a file has been created which con- 
tains such a list of items. 

Usage : 

command [all path] 

Where "path" is the name of a segment containing characters 
to be placed on the command line. 

Note : 

This active function, by its nature, makes it fairly easy 
to exceed the default command line length (see set__com__line) 
and the maximum number of arguments accepted by the standard 
command processor. 
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Active Function 
Author-Maintained Library 
John C. Klensin 
575 Technology Square 
Fifth Floor, Ext. 3-6217 

2/20/74 



Name ; bit_count 

This active function is used to obtain cuid return the bit 
count on a given segment. It is likely to be useful when the 
presence of information in a segment is more interesting than 
whether or not it exists. 

Us age : bit_count segname 

Where 

segname is the relative pathname of the file whose 

bit count is to be returned. 

Note: If the file is not present, a value of *'-l" is returned. 

Otherwise the bit count is returned. This permits testing 
for "present and bit count greater than zero" by a single 
test that does not produce errors. 

Example : Used in an exec com context, this function might appear 
in a statement as follows: 

&if [greater [bit_count] mailbox 0 ] 
&then &print mail! 



c) Copyright 1974, Massachusetts Institute of Technology 
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center 



Active Function 
Author-Maintained Library- 
Student Information Processing Board 
Room 39-200, Ext. 3-7788 

9/6/74 



Ncune ; center 

This active function returns its first argument centered in 
a field of blanks whose length is specified by the second argument. 
The return value is enclosed in quotes. 

Usage ; 

[center string length] 

1) string is the string to be centered. 

2) length is the size of the field of blanks. 



Example : 

dprint -he Ccenter &1 13] &l,list 
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Active Function 
Author-Maintained Library 
John C. K lens in 
575 Technology Square 
Fifth Floor, Ext. 3-6217 

10/31/73 

Name ; dwd 

This active function returns the name of the default working 
directory (the home directory unless it has been changed by 
the command change_def ault^wdir (cdwd) ) in a fashion similar 
to the active functions wd and pd for the working and process 
directories . 

Usage ; dwd 
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exist any 



Active Function 
Author-Maintained Library 
John C. Klensin 
575 Technology Square 
Fifth Floor, Ext. 3-6217 

2/20/74 



Name : exi s t__any 



This active function accepts one or more relative pathnames , 
possibly containing stars or question marks, as argiaments. If any 
of the names is found (or any name is found) that matches one of 
the star names, the function returns "true." Otherwise, it returns 
"false." 

Usage ; exist_any -namel- ... 
Where 

-namei- are relative pathnames. 

Note ; The routine returns "true" as soon as a single name match 
is found, so it does not scan the rest of the input names. 

Example ; Used in an exec__com context, this function might appear 
in a statement as follows: 

&if [exist_any **.list] 

Stthen sprint you have list segments 



(cj Copyright 1974, Massachusetts Institute of Technology. 
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Active Function 
Author-Maintained Library 
John C. Klensin 
575 Technology Square 
Fifth floor. Ext. 6217 
1/18/71 

Name ; Id 

The active function Id returns the pathname of the original 
login directory of the process in which it is invoked. 

Usage; 



command [Id] 
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translate 



Active Function 
Author-Maintained Library 
Joseph W. Dehn III 
Room 39-200, Ext. 3-7788 

11/15/74 



Name ; translate 

This active function may be used to translate a character 
string in a manner similar to the translate built-in function of 
PL/I . 



In the first form, the returned string will be the string 
formed by substituting for each character occurring in "old" 
the corresponding character in "new". This is identical to the 
PL/I function. 

In the second form, the translation is specified by a control 
option, which may be: 



Usage: 



[translate string new old] 



or 



[translate string opt] 



-Ic 



-uc 



to translate to upper case 
to translate to lower case 



Exa mple s ; 



print_string [translate "Test String" -uc] 
TEST STRING 



print__string [translate 10/13/74 - /] 
10-13-74 



